MantisBase v0.3.6 Release

A Cleaner, More Consistent API

MantisBase v0.3.6 is a housekeeping release, marking the start of systemic cleanup. We cleaned up the REST API so every route follows the same conventions, scoped authentication to the entity it belongs to, and gave admin management its own home. There are a few breaking changes, but migration is a quick find-and-replace in most cases.

Why the change?

As MantisBase grew, the API surface accumulated small inconsistencies. Auth took the target entity in the request body while everything else was path-based. File serving lived at `/api/files/...` while the rest of the API was versioned under `/api/v1/`. Admin operations were split awkwardly between the auth namespace and the system namespace.

v0.3.6 makes the whole surface predictable. Everything now lives under `/api/v1/` in a clear set of namespaces:

Authentication is now per-entity

Previously you told MantisBase which entity to authenticate against by putting it in the request body:

# Old (v0.3.5)
curl -X POST http://localhost:7070/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"entity": "users", "identity": "user@example.com", "password": "pw"}'

Now the entity lives in the URL, which is more RESTful and lets each auth entity have its own clearly addressable endpoints:

# New (v0.3.6)
curl -X POST http://localhost:7070/api/v1/auth/users/login \
  -H "Content-Type: application/json" \
  -d '{"identity": "user@example.com", "password": "pw"}'

The same pattern applies to refresh and logout:

curl -X POST http://localhost:7070/api/v1/auth/users/refresh \
  -H "Authorization: Bearer <token>"

curl -X POST http://localhost:7070/api/v1/auth/users/logout \
  -H "Authorization: Bearer <token>"

The `<entity>` must be a registered `auth`-type entity that isn’t a system table and has the API enabled — otherwise you’ll get a clean `404 Route Not Found`.

One more thing: the login response is now wrapped in MantisBase’s standard envelope, so it matches every other endpoint:

{
  "status": 200,
  "data": {
    "token": "eyJhbGci...",
    "user”: { "id": "123456"”, "email": "user@example.com", "name": "John Doe" }
  },
  "error": ""
}

Admins get their own namespace

Admin authentication and account management now live entirely under `/api/v1/sys/admins/`, and admin CRUD is fully supported:

# Create the very first admin (only works when none exist yet)
curl -X POST http://localhost:7070/api/v1/sys/admins/setup \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "adminpassword"}'

# Admin login
curl -X POST http://localhost:7070/api/v1/sys/admins/login \
  -H "Content-Type: application/json" \
  -d '{"identity": "admin@example.com", "password": "adminpassword"}'

# Manage admin accounts (requires admin auth)
curl http://localhost:7070/api/v1/sys/admins                   # list
curl http://localhost:7070/api/v1/sys/admins/:id               # get one
curl -X POST   http://localhost:7070/api/v1/sys/admins ...     # create
curl -X PATCH  http://localhost:7070/api/v1/sys/admins/:id ..  # update
curl -X DELETE http://localhost:7070/api/v1/sys/admins/:id     # delete

The old `POST /api/v1/auth/setup/admin` endpoint is gone — use `/api/v1/sys/admins/setup` instead.

Files and settings

File serving is now versioned, matching the rest of the API:

# Old:  http://localhost:7070/api/files/posts/photo.jpg
# New:  http://localhost:7070/api/v1/files/posts/photo.jpg

curl http://localhost:7070/api/v1/files/posts/photo.jpg

And application settings are exposed under the system namespace:

curl http://localhost:7070/api/v1/sys/settings/config   # read
curl -X PATCH http://localhost:7070/api/v1/sys/settings/config \
  -H "Content-Type: application/json" -d '{ ... }'             # update

Under the hood: lighter on memory

Beyond the visible API changes, we refactored how routes are registered. Instead of building a dedicated set of CRUD handlers for every single entity, MantisBase now uses centralized, generic handlers that resolve the target entity from the request path. Schema route handlers were similarly decoupled from the schema object. The result is the same behavior with a smaller memory footprint — especially noticeable on deployments with many entities.

We also refreshed the bundled dependencies (WolfSSL, nlohmann/json, jwt-cpp, spdlog, and the mb-admin dashboard) and fixed a build-target clash around `ztd`.

Something is broken, oh no!

As a result of the API changes, we ended up breaking the admin dashboard. Currently, v0.3.6 admin dashboard is unusable and requires reworking to bring it up to bar. That’s already being worked on and we will push an update once resolved.

Upgrading from v0.3.5

Most apps only need three mechanical updates:

1. Auth calls: move the entity from the body into the path
   (`/api/v1/auth/login` + `"entity": "users"` → `/api/v1/auth/users/login`).

2. Admin calls: repoint admin auth/setup to `/api/v1/sys/admins/...`.

3. File URLs: add the 1 segment (`/api/files/...` → `/api/v1/files/...`).

If you parse the login response, unwrap it from the new `{ status, data, error }` envelope.

---

That’s it — grab v0.3.6 from the releases page, and check the updated Authentication API and API Reference docs for the full details.