API Reference

Base path and transport

http://<host>:<port>/api/v1/

Default: http://localhost:9000. The web frontend is served at /web/. HTTPS is recommended for production (configure a reverse proxy — nginx or Caddy — in front of Hive).

Authentication — Bearer tokens

All protected endpoints require a Bearer access token:

Authorization: Bearer <access_token>

Access tokens are short-lived (default: 15 minutes, configurable as access_token_expires_in in minutes). Use the refresh token endpoint to obtain a new access token without re-authenticating. Refresh tokens rotate: each use issues a new refresh token (old one invalidated). Default refresh token lifetime: 30 days (refresh_token_expires_in=43200 minutes).

Token lifecycle (frontend implementation)

The frontend's apiFetch() function in frontend/api.js handles token lifecycle transparently:

// Proactive refresh: if access token expires in < 60 seconds, refresh first
// On 401 response: attempt token refresh once, then retry original request
// On refresh failure: redirect user to login screen

// Token storage: localStorage
// Keys: "access_token", "refresh_token", "token_expiry" (Unix timestamp)

Authentication Endpoints

All authentication endpoints live under /api/v1/auth/ and are handled by AuthEndpointsGenerator in hive-http. The implementation in frontend/auth.js wraps these endpoints.

Login — request and response

Content-Type: application/json

{
  "username": "admin",
  "password": "your-secure-password"
}

{
  "access_token":  "eyJhbGciOiJIUzI1NiIsIn...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsIn...",
  "expires_in":    900,
  "token_type":    "Bearer",
  "user": {
    "id":       1,
    "username": "admin",
    "role":     5
  }
}

Refresh token — request and response

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsIn..."
}

{
  "access_token":  "eyJhbGciOiJIUzI1NiIsIn...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsIn...",
  "expires_in":    900
}

Registration modes

Error responses

// 401 Unauthorized — wrong credentials or expired token
{ "error": "Invalid credentials" }

// 403 Forbidden — authenticated but not permitted
{ "error": "Forbidden", "details": "Insufficient role" }

// 409 Conflict — username already taken
{ "error": "Username already exists" }

Model Definition Endpoint

The single most important endpoint in Hive. The frontend reads this once at startup (cached in localStorage for 3 hours) and derives all navigation, CRUD forms, list columns, and FK dropdowns from it.

Handled by ModelDefinitionEndpointsGenerator. Returns the full ModelDefinition registry — one object per registered model across all loaded plugins.

Full response structure (one model entry)

[
  {
    "name":          "note",
    "plugin":        "slip_box",
    "group":         "Slipbox",
    "title_column":  "title",
    "operations":    ["create", "read", "update", "delete", "list"],
    "cache_enabled": true,
    "readonly":      false,
    "columns": [
      {
        "name":        "id",
        "flags":       2056,        // INTEGER | AUTO | HIDDEN bitmask
        "type":        "INTEGER",
        "primary_key": true,
        "hidden":      true,
        "auto":        true,
        "mandatory":   false,
        "mutable":     false
      },
      {
        "name":        "title",
        "flags":       257,         // TEXT | MANDATORY bitmask
        "type":        "TEXT",
        "hidden":      false,
        "mandatory":   true,
        "mutable":     true,
        "readonly":    false
      },
      {
        "name":        "content",
        "flags":       514,         // TEXTAREA | MUTABLE
        "type":        "TEXTAREA",
        "hidden":      false,
        "mandatory":   false,
        "mutable":     true
      },
      {
        "name":        "parent_id",
        "flags":       1028,        // INTEGER | FOREIGN_KEY
        "type":        "INTEGER",
        "foreign_key_model": "note",
        "hidden":      false,
        "mandatory":   false,
        "mutable":     true
      }
    ],
    "custom_list_actions":   [],
    "custom_create_actions": [],
    "custom_read_actions":   []
  }
  // ... more models
]

ColumnDefinitionFlag bit values

Auto-Generated Model Endpoints

For every registered model with enabled operations, ModelEndpointGenerator generates these routes at startup. The set of enabled operations is controlled per model via ModelDefinition::set_rest_operations() or set_all_rest_operations().

Create request example

Content-Type: application/json
Authorization: Bearer <access_token>

{
  "title":     "My first note",
  "content":   "# Hello\n\nThis is **Markdown**.",
  "parent_id": null,
  "map_id":    3
}

{
  "id":         42,
  "title":      "My first note",
  "content":    "# Hello\n\nThis is **Markdown**.",
  "parent_id":  null,
  "map_id":     3,
  "path":       "/maps/3/42",
  "note_order": 0,
  "created_at": "2026-06-26T10:30:00Z",
  "updated_at": null
}

List response format

// GET /api/v1/note?page=1&page_size=20

{
  "items":       [ ... ],       // array of entity objects
  "total":       142,           // total records matching query
  "total_pages": 8,             // ceil(total / page_size)
  "page":        1,
  "page_size":   20
}

Error response format

// 400 Bad Request — missing mandatory field
{
  "error":   "Validation failed",
  "details": "Field 'title' is mandatory and was not provided."
}

// 403 Forbidden — validator rejection
{
  "error":   "Forbidden",
  "details": "You do not have permission to modify this record."
}

// 404 Not Found
{
  "error":   "Not found",
  "details": "No record with id=999 in model 'note'."
}

// 405 Method Not Allowed — operation not enabled for this model
{
  "error":   "Method not allowed",
  "details": "Operation 'delete' is not enabled for model 'history'."
}

QueryParams — List Endpoint Parameters

The frontend's QueryParams class (in frontend/api.js) constructs the query string for list requests. All parameters are optional.

QueryParams usage in frontend API

// From frontend/api.js — QueryParams class
class QueryParams {
    constructor() {
        this.page      = 1;
        this.page_size = 20;
        this.sort      = 'id';
        this.order     = 'asc';
        this.q         = null;      // search query
        this.filters   = {};        // { field: value }
    }

    toQueryString() {
        // Serialises to URL query string
        // Excludes null/undefined values
    }
}

// list_all_entities() — auto-pages to collect up to 1000 records
// Used for FK dropdown population (SelectAll for referenced models)
async function list_all_entities(model_name, qp = new QueryParams()) {
    let all = [];
    let page = 1;
    while (all.length < 1000) {
        qp.page = page++;
        const result = await list_entities(model_name, qp);
        all = all.concat(result.items);
        if (all.length >= result.total) break;
    }
    return all;
}

Example list request with parameters

GET /api/v1/note?page=2&page_size=10&sort=created_at&order=desc&filter[map_id]=3
Authorization: Bearer <access_token>

Custom Action Endpoints

Models can register named custom actions via ModelDefinition::add_custom_list_action(), add_custom_create_action(), and add_custom_read_action(). These appear as buttons in the frontend (implemented by executeCustomAction() in frontend/crud.js) and are dispatched to registered trigger handlers.

Custom action registration

// In ModelDefinition builder (C++ plugin code)
ModelDefinition("note")
    .add_custom_read_action("export_html",  "Export as HTML")
    .add_custom_read_action("duplicate",    "Duplicate note")
    .add_custom_list_action("export_all",   "Export all notes")
    .add_custom_create_action("import_md",  "Import from Markdown file")

Health, Info & Super Admin Endpoints

Operational endpoints handled by InfoHealthEndpointsGenerator and SuperAdminEndpointsGenerator.

HTTP/1.1 200 OK
{
  "status": "ok",
  "db":     "ok"
}

{
  "version":     "2.0.0",
  "plugins":     ["core", "slip_box",
                  "dictionary", "repetition"],
  "started_at":  "2026-06-26T08:00:00Z",
  "access_mode": "PublicFullAccess",
  "registration_mode": "Free"
}

Frontend Routes

Static files are served by WebEndpointsGenerator from the directory specified by --frontend-path / -s flag (default: ./frontend).

Complex Filtering — Planned Enhancement

Complex JSON-based filter expressions are a planned enhancement. The design is documented in the project backlog. Currently only simple equality filters (filter[field]=value) and search query (q) are available.

Planned filter operators

Example planned complex filter

// GET /api/v1/note?filter={"and":[{"map_id":{"eq":3}},{"title":{"like":"%hive%"}}]}

{
  "and": [
    { "map_id":  { "eq": 3 } },
    { "title":   { "like": "%hive%" } },
    { "or": [
        { "parent_id": { "is_null": true } },
        { "note_order": { "gt": 0 } }
    ]}
  ]
}