# Hister API Endpoints for Document Operations: Complete CRUD Reference

> Discover Hister API endpoints for complete CRUD document operations including batch uploads and PDF support. Access the full REST API reference to manage your indexed documents efficiently.

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

---

**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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/server/api.go) and exposed under the `/api/` base path.

| Operation | Method | Path | Source Location |
|-----------|--------|------|-----------------|
| Add document | `POST` | `/api/add` | [api.go: L46-L53](https://github.com/asciimoo/hister/blob/master/server/api.go#L46-L53) |
| Legacy add | `POST` | `/add` | [api.go: L25-L33](https://github.com/asciimoo/hister/blob/master/server/api.go#L25-L33) |
| Add PDF | `POST` | `/api/add_pdf` | [api.go: L84-L91](https://github.com/asciimoo/hister/blob/master/server/api.go#L84-L91) |
| Retrieve document | `GET` | `/api/document` | [api.go: L66-L71](https://github.com/asciimoo/hister/blob/master/server/api.go#L66-L71) |
| Update label | `POST` | `/api/label` | [api.go: L28-L33](https://github.com/asciimoo/hister/blob/master/server/api.go#L28-L33) |
| Batch update | `POST` | `/api/update` | [api.go: L18-L25](https://github.com/asciimoo/hister/blob/master/server/api.go#L18-L25) |
| Delete documents | `POST` | `/api/delete` | [api.go: L27-L34](https://github.com/asciimoo/hister/blob/master/server/api.go#L27-L34) |
| Batch operations | `POST` | `/api/batch` | [api.go: L70-L78](https://github.com/asciimoo/hister/blob/master/server/api.go#L70-L78) |
| Preview HTML | `GET` | `/api/preview` | [api.go: L87-L94](https://github.com/asciimoo/hister/blob/master/server/api.go#L87-L94) |
| Raw file | `GET` | `/api/file` | [api.go: L95-L102](https://github.com/asciimoo/hister/blob/master/server/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`](https://github.com/asciimoo/hister/blob/main/server/api.go).

```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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/server/api.go).

```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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/server/api.go).

```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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/server/api.go).

```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`](https://github.com/asciimoo/hister/blob/main/server/api.go).

```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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/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`](https://github.com/asciimoo/hister/blob/main/server/api.go).