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", "access_token_expires_at"

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"
}

{
  "user_id":                  1,
  "access_token":             "3f9c2a…",
  "access_token_expires_at":  1782115200,
  "refresh_token":            "b81d44…",
  "refresh_token_expires_at": 1784707200
}

Refresh token — request and response

{
  "refresh_token": "b81d44…"
}

{
  "user_id":                 1,
  "access_token":            "a4e7f1…",
  "access_token_expires_at": 1782116100,
  "refresh_token":           "c92e55…"  // present only when
                                        // the token was rotated
}

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",
  "map_id":         3,
  "parent_note_id": null
}

{
  "id":             42,
  "title":          "My first note",
  "map_id":         3,
  "parent_note_id": null
}

List response format (real keys)

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

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

Error response format

Errors are returned as plain-text messages with the HTTP status coming from the validator's OperationResult or the endpoint checks:

// 400 Bad Request — invalid paging
Invalid page size. It must be 5 at least

// 401 Unauthorized — missing/expired/revoked token
(from AccessTokenContext.status)

// 403 Forbidden — validator rejection
You are not authorized...

// 405 Method Not Allowed — operation not enabled for this model
Method not allowed for model history.

// 500 Internal Server Error — persistence failure
Saving the note failed. Error: ...

QueryParams — List Endpoint Parameters

List endpoints accept these query-string parameters, parsed by ModelEndpointGenerator. All parameters are optional.

QueryParams usage in frontend API

// From frontend/api.js — QueryParams is a small builder over a Map
export class QueryParams {
    #params = new Map();

    add(key, value) { ... }          // add any parameter
    sort(sort, order = null) { ... } // convenience for sort + order
    toString() { ... }               // serialise to query string
}

// list_entities(entity, additional_params, page_number = 1, page_size = 20)
// sets page_number + page_size and appends additional params.

// list_all_entities() — auto-pages with page_size=100 until all
// records are collected (used for FK dropdown population).

Example list request with parameters

GET /api/v1/note?page_number=2&page_size=10&sort=created_at&order=desc&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(). Custom actions are metadata, not extra REST routes: they ship in the /api/v1/model_definition response and the frontend renders them as navigation buttons that jump to another model's list/create/read view with pre-filled parameters.

Custom action structure

// C++ side — in ModelDefinition builder (plugin code):
// add_custom_action(Crudl operation, target model, label, params map)
ModelDefinition md("note", "slip_box");
md.add_custom_read_action("note_navigation", "Explore",
                          {{"note_id", "{id}"}})
  .add_custom_list_action("wanted_note", "Wanted notes", {});

// Serialized into model_definition → consumed by crud.js:
{
  "crudl":      "Read",            // which view to open
  "model_name": "note_navigation", // target model
  "label":      "Explore",         // button text
  "params":     { "note_id": "{id}" }  // "{id}" = current record id
}

The frontend groups action buttons by target model on the read view. The "{id}" placeholder is substituted with the current entity's ID, which makes custom actions the bridge between generated CRUD screens and virtual models like note_navigation (backed by InsteadOf triggers).

Health, Info & Super Admin Endpoints

Operational endpoints handled by InfoHealthEndpointsGenerator and SuperAdminEndpointsGenerator.

Requests from users below UserRole::SuperAdmin receive 403 Forbidden: only SuperAdmin can perform this action.

{
  "name":              "Hive",
  "description":       "…",
  "version":           "…",
  "build_time":        "…",
  "environment":       "Production",
  "host":              "http://localhost",
  "port":              9000,
  "frontend_port":     9000,
  "access_mode":       "PublicFullAccess",
  "registration_mode": "Free",
  "default_user_role": "Reader"
}

HTTP/1.1 200 OK

Server is healthy — includes formatted
uptime (seconds/minutes/hours/days
since startup).

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 } }
    ]}
  ]
}