uebliche

Appearance

Personal Totem API ​

Endpoints for uploading, listing, and fetching personal totem models.

Compatibility: every endpoint listed below is also reachable under /v1/api/profile/... to keep legacy clients (e.g., the Totem mod) working.

Permissions ​

  • totem:read for reads
  • totem:write for uploads

If the permission node is not present in the database, the endpoint allows access by default.

Endpoints ​

GET /v1/profile/personal-totem ​

Returns the current active personal totem for the authenticated user.

Query:

  • includeModel=true to inline the model JSON instead of returning a URL.

GET /v1/profile/personal-totem/history ​

Returns recent models for the authenticated user.

Query:

  • limit (default 10, max 50)

Returns the public totem gallery (all models), marking which entry is currently active for the caller.

Query:

  • limit (default 200, max 500)
  • sort (selected, created, last_used, name)
  • order (asc, desc)

Response notes:

  • Gallery items omit fields when the stored value is empty (for example rating, author, and timestamps), so clients should treat missing fields as null.
  • Gallery items include itemModelUrl so clients can fetch previews directly.

GET /v1/profile/personal-totem/model/{itemModelId} ​

Returns a specific model by id (must belong to the caller or be active).

When PERSONAL_TOTEM_PUBLIC_API is enabled (as in production deployments), this endpoint also serves any gallery model by itemModelId, so clients can preview the public entries in the gallery.

Response notes:

  • itemModelUrl is a public CDN URL (for example https://totem.uebliche.net/{modelId}.json) so clients can fetch the model directly.

POST /v1/profile/personal-totem ​

Upload a new model or activate an existing one.

Body:

json
{
  "data": { "format": "bbmodel", "data": "base64" },
  "itemModelId": "optional ObjectId",
  "fileName": "optional",
  "rating": { "content": "sfw|nsfw|nsfl", "age": 0 },
  "author": { "id": "uuid", "name": "optional", "description": "optional" }
}

Notes:

  • data and itemModelId are mutually exclusive.
  • rating/author are optional; author id defaults to the caller when omitted.
  • rating.age is expected to be one of 0, 16, 18, 21.

Model metadata ​

Responses can include:

  • itemModelRating with { "content": "...", "age": 0 }
  • itemModelAuthor with { "id": "uuid", "name": "...", "description": "..." }
  • selectedCount, rating, and author on gallery/history items
  • itemModelUrl points at the public CDN URL for the model payload.
  • New uploads also store their keys without the totem-models/ prefix, so Mongo records directly show totemId.json.