Use ordinary HTTPS/JSON (REST) for applications and client libraries, or connect an AI agent through MCP. Both use the official portal's API and the manager's existing permissions. No database access is needed.
Host (tenant 000): when explicitly enabled, Host uses its own A0000 database and bank 0 only. It has no positive-bank, location or unit resources, and no Equipment API. Manager and service administration retain their normal tab, scope and operation checks. Resource operations return 404, including through MCP. Host uses the Team/Portal layout and theme. Available in this source branch; beta/production activation requires deployment and domain configuration.
More1 tools
These tools use POST /api/v1/tenant/tools/..., a reusable manager bearer token and JSON. Requires an active manager, More1 (29), Bank Read and at least one site-bound resource grant; a bank or location grant is sufficient. More1 is a tenant-level workspace tool. The trusted site owns the tenant; no tenant or bank selector is accepted. Requests are bounded to 8 KiB, responses are no-store; do not persist tool inputs. Calculations do not change data.
Test email (alfa; not yet released to beta/production)
QueueMyTestMail — POST /api/v1/tenant/tools/test-mail accepts only {}. Uses a fresh active-manager account and the same More1, Bank Read and same-site grant requirements above. The recipient is the signed-in manager’s current registered email; recipient, tenant, sender and message cannot be supplied by the client. The fixed test message is queued once, at most one request per manager and tenant per minute. HTTP 202 {"recipient":"effective@example.com"} confirms enqueue, not delivery. The existing exact-domain restriction permits nortec.dk, kombinetech.com and arendt.dk; other valid addresses are redirected to jens@arendt.dk, which is then reported as the effective recipient. Business tenants use Jobs Mails (5); Host keeps its separate existing outbox. HTTP 400 means invalid stored email or nonempty input; 401/403 mean authentication/authorization failure; 429 means wait for Retry-After. On timeout or 503 the enqueue outcome may be uncertain: do not automatically retry. Check the inbox before making a new explicit request. Portal Web requires its authenticated cookie and CSRF token.
ConvertToolTime — POST .../time accepts {format,value,timeZone,offset?}. Formats: ms2000, mi2000, ss2000, utc, local. Numbers are decimal strings, never JavaScript numbers. Use an explicit browser IANA zone such as Europe/Copenhagen; UTC input is ISO 8601 with Z or an offset. Local input is an offset-free ISO wall time. Epoch is 2000-01-01T00:00:00Z. The installed Kombine.Flex.Time library defines MS2000 (milliseconds), MI2000 (minutes) and SS2000 (seconds). These MI2000 values are UTC minutes, distinct from reservation Log5 local minutes.
A successful response has success=true and result:{ms2000,mi2000,ss2000,utc,local,timeZone,offset,dateInputRounded,millisecondRemainder,secondRemainder}. Integer MS2000 preserves individual milliseconds; date input truncates to the library's 2 ms precision and flags any loss. Whole seconds/minutes truncate; remainders report the lost part. MS2000 range: 0–252455615999999; reversible MI2000: 0–2147483646; SS2000: 0–2147483647. MI2000/SS2000 output is null beyond its range, avoiding wraparound. UTC and local results must fit years 1–9999. The API never uses its server-local zone.
Time validation returns HTTP 400 with success=false,error,result:null,offsetChoices. Errors: invalid-time-value, invalid-time-format, invalid-time-zone, time-out-of-range, invalid-local-time (DST gap), ambiguous-local-time and invalid-time-offset. An overlap returns both {offset,utc} choices; explicitly resubmit the chosen offset (e.g. "offset":"+01:00"). Never silently choose an occurrence.
InspectToolKid — POST .../kid accepts {"kid":"YOUR_KID"} (maximum 2048 characters). Returns {canonicalKid,normalized,fields:[{name,value,enumName,enumNumber,index}]}. Values/numbers are strings. Uses the installed Kid parser and actual writable data fields, including MainId; zero/default fields are omitted. Settings/Icons retain zero-based indexes. Scalar aliases and derived properties are not repeated. Normalized warns that the parser changed or ignored input; compare canonicalKid. Inspection does not resolve an object, prove existence or grant access.
Handle 400 invalid input or KID; 401 sign in again; 403 missing Tab/read/scope; 503 retry later. Client regeneration and packaged downloads are deferred to beta preparation.
The new GET /api/v1/public/statistics/running-units endpoint (without temperature) returns the complete running list without pagination; unitType and cycle are nullable decoded machine fields. Storage limits cause HTTP 503 instead of a partial list. See the running machines example. Refresh every 15 seconds; X-Portal-Refresh-After-Ms aligns clients with cache expiry.
Widgets for your website
Live examples of the same JavaScript widgets used by the anonymous portal overview. No iframe, account or API key.
Copy an example into your own page. Use the API hostname for your tenant and the matching release environment. The module creates its own Shadow DOM and loads its stylesheet. Widgets have transparent backgrounds and adapt to the container size and aspect ratio. For mountWidgets and mountProgressWidgets, style each card with #kombine-widget::part(widget-container); set its background, border and optional aspect-ratio there. For mountCycleWidget, style and size the host element itself. Labels, names and default colors come from that API. The optional brandLightTokens and brandDarkTokens provide validated tenant CSS custom properties for light and dark presentation. Load the tenant fonts in your own page to use those typefaces; otherwise the declared fallbacks apply. The optional brandIconUrl is the tenant public icon; it is null if a relative icon cannot be resolved against the configured tenant Web origin. WashDoc displays this icon beside the document KID. Permit that icon origin in img-src when using Content Security Policy. The host element controls available width: cards use a 300px minimum and wrap automatically. Use machineCount: 1, 2 or 3 for distinct random running machines. Use mountProgressWidgets for a specific unit, location or bank KID.
The module sends credential-free GET requests only. These public widget reads allow external origins; manager/session operations retain their exact-origin CORS restrictions. If your website uses Content Security Policy, allow the API origin in script-src, connect-src, img-src and style-src; tenant styling and dynamic progress require inline styles, the purchase chart requires data: in img-src, and WashDoc previews require blob: in img-src. Use HTTPS and a browser with ES modules, Shadow DOM, fetch and AbortSignal.timeout. Do not embed credentials. The data is live and may be unavailable; 503 means unavailable, never zero. Each card retries automatically and marks retained values as unavailable after a failed refresh. The ready promise reports initialization errors; set unavailableText for a localized initial failure message. Call destroy() when removing or replacing a widget group. Removing a host stops its polling automatically.
Running count refreshes every 15 seconds; purchases, reservations and machine pool every minute; active users every minute (the API caches their count for five minutes). Requests share one snapshot within the page. Countdown runs locally every second using server time, retains each selected machine and shows completion for 20 seconds. Pool bounds and public fields are unchanged; images are API-generated SVGs. Amounts remain separated by currency.
GetPublicWidgetPresentation — GET /api/v1/public/widgets
Available in this source branch; unreleased. Deploy API and Web from the same release before using this on a public website.
KID: Unit / Location / Bank
Use mountProgressWidgets(host, { apiBase, kid, language }) with a canonical Unit, Location or Bank KID belonging to this API site. No login is required. Unit displays one card; Location includes all public units in that location; Bank includes all public units in every location of the bank. Deleted objects and disabled locations are excluded; disabled units and child units are included. No account data, temperature or additional settings are published. Each page contains up to 100 units; Load more appends subsequent pages. Loaded pages refresh every minute with fresh cursors. Unknown timing is labelled; completed runs remain at 100%. Pages are not a frozen snapshot.
GetPublicScopedUnitProgress — GET /api/v1/public/widgets/progress/{kid}?pageSize=100. Follow nextCursor using cursor and the same pageSize. Cursors expire after 15 minutes. 400: invalid or cross-tenant KID, page size or cursor; 404: no public unit; 503: temporarily unavailable, respect Retry-After. An empty location/bank returns an empty items array. These public GET operations allow external origins without credentials.
Public WashDoc widget (unreleased)
GetPublicCycleWidget — GET /api/v1/public/widgets/cycle is a credential-free, tenant-bound publication. Use the canonical cycleKid to show one document, or unitKid to follow that unit's stored WashDocId, including its last completed document. The options are mutually exclusive. Omit both to follow the most recently started currently running public machine; this is not a random pool. The API site determines the tenant; callers cannot override it.
Only non-deleted banks, locations and units in enabled locations qualify under public visibility. Visibility is rechecked through a bounded snapshot cached for up to 60 seconds. The response contains cycleKid, unitKid, display-only cycleKidText from Kid.ToDocId (unit identity plus ~documentId), localized unitName/locationName, startedAtUtc, nullable endedAtUtc, finished, text-free graphSvg and refreshAfterSeconds: 15 while running, 0 for a completed pinned document (stop polling), or 60 when following a unit/latest machine to discover a new document. The simplified graph shares data acquisition, legacy numeric decoding, cycle boundaries, edge data and renderers with the full graph. It shows at most the first two available curves in the same order as the graph picker, arranged in two compact vertical bands with a clear gap between the curves and room for the caption below. Gradient fills span the full width. Both gradient fills continue to the widget bottom. The widget reserves space above the graph for the document KID badge. The first curve fades to transparent at the widget bottom behind the second curve. Curve colours match the full WashDoc chart. Preview strokes stay 1.8 CSS pixels wide at every widget size, and the gradient is lighter for the compact overlapping layout. Caption text has a 50%-opacity white outline. It is a graphical impression without axes, labels, numeric values or a raw measurement table. It publishes no resident, payment, credential or arbitrary-setting data. Full document/table/Excel operations remain authenticated and authorized.
A document without drawable numeric measurements still returns HTTP 200 with names, KIDs, timestamps and completion status. In that case graphSvg is null; show a no-measurements message instead of creating an image or treating it as a loading failure. The refresh rules still apply: a completed pinned document stops, while a running document may acquire measurements on a later refresh. Missing/inaccessible documents remain 404, data limits remain 422, and temporary failures remain 503.
mountCycleWidget from /docs/widgets.mjs renders one widget with the graph as cover, machine/location names and date/time. It loads lazily while visible, refreshes running documents every 15 seconds without overlapping requests, stops when a pinned document finishes, pauses when hidden and returns ready and destroy(). Destroy before replacing the host. It uses Shadow DOM and the bundled stylesheet. For Content Security Policy, allow the API origin for script-src, style-src and connect-src, plus blob: for img-src. No API key or bearer token is required. For WashDoc, ready resolves after the first visible read attempt, including when the card displays an unavailable message; it does not guarantee document data.
<div id="washdoc" style="width:min(100%, 340px); aspect-ratio:4 / 3; background:#fff; border:1px solid #d1d5db; border-radius:12px; overflow:hidden"></div>
<script type="module">
import { mountCycleWidget } from "https://YOUR-TENANT-API/docs/widgets.mjs";
const widget = mountCycleWidget(document.getElementById("washdoc"), {
apiBase: "https://YOUR-TENANT-API", cycleKid: "CANONICAL_DOC_KID", language: "en-GB"
});
widget.ready.catch(console.error);
// Use unitKid: "CANONICAL_UNIT_KID" instead of cycleKid to follow one unit.
// Omit both KID options to follow the newest running public machine.
// widget.destroy();
</script>
HTTP 400: invalid, noncanonical, cross-tenant or conflicting KIDs; 404: no public machine/document; 422: no numeric graph or document exceeds graph limits; 503: busy or unavailable, respect Retry-After: 60. An unavailable graph is never fabricated. Responses are no-store; anonymous GET-only CORS allows external sites without credentials. Implemented locally, not deployed; release API and Web together. Packaged client regeneration remains deferred to beta preparation.
Addresses and automatic coordinates
Available in this source branch; not yet deployed. These operations support Bank, Location, Unit and resident User. Tenant, manager and installer addresses are excluded. Supply one canonical object KID from the current site. Address values are the object's own settings; parents are not inherited.
Operation ID
Method and path
Purpose
GetObjectAddress
GET /api/v1/addresses/{kid}
Read settings and revision
UpdateObjectAddress
PUT /api/v1/addresses/{kid}
Save Address and Zip, then resolve coordinates
LookupObjectCoordinates
POST /api/v1/addresses/{kid}/lookup
Deliberately resolve the current address again
SetObjectCoordinates
PUT /api/v1/addresses/{kid}/coordinates
Save a manual coordinate pair
SetObjectCoordinateProvenance
PUT /api/v1/addresses/{kid}/provenance
Change coordinate provenance
Requires an active manager, an assigned Tab (Users2 for residents), a matching resource grant, Bank Read and the object's Read permission. Unit also requires Location Read. Every write additionally requires the object's Write permission. Bank and User need a bank-wide or tenant-wide grant; location-only grants cannot edit shared bank or resident addresses. Objects and parents must exist and not be deleted; disabled locations require tenant-wide access. Rights are rechecked under storage locks before each transaction.
Use your site's HTTPS base URL as API, the returned canonical object ID as KID, and refresh the revision between commands. Both address strings are required, may be empty and are trimmed; maximum lengths are 512 and 64 characters. Control characters are rejected. A change to either Address or Zip triggers at most one coordinate lookup. A bare postal code additionally triggers one postal-city lookup, including in manual mode. The trusted site tenant selects the country: Team, Nortec and Electrolux use DK (four digits), Washco uses GB (full alphanumeric postcode, for example SW1A 1AA), and Finelec uses FI (five digits, for example 00100). Other tenants skip postal completion. The country cannot be selected by the client. Address coordinate lookups also use the mapped country as their region bias. An exact, unambiguous postal-city result is saved in Zip as, for example, 7470 Karup J. Existing city text is preserved; missing, ambiguous or failed postal results leave the input unchanged. Manual coordinates are never changed by postal completion. If the postal response lacks a city, the full address response may supply it when country and postal code match exactly. In manual mode this address lookup completes Zip only; it preserves coordinates and provenance. Neither request is retried. Use the returned zip and revision for subsequent edits. Unchanged inputs skip lookup; use the explicit lookup operation to retry. No background retries are scheduled.
The address transaction inserts both fields and clears old automatic Latitude and Longitude and sets AutoLatitudeLongitude to 0. Successful lookup inserts the new pair and UTC month (1–12) together. Provider failure leaves automatic coordinates empty. Manual provenance 30 protects the pair during address changes. Explicit lookup replaces a manual pair only on success. Concurrent edits return Superseded without overwriting newer values. History is append-only: bank Log2 for Bank/Location/Unit, bank Log7 for User, with Sync=0; success confirms storage, not device acknowledgement.
LookupObjectCoordinates also supports a Location with an empty Address: it looks up the stored Name plus Zip. Only on success is Name saved as Address in the same transaction as Latitude, Longitude and the UTC month. Failed name-based lookups leave these values untouched; missing or invalid Name/Zip returns IncompleteAddress. A concurrent rename supersedes the result. No extra request or automatic retry is added.
The response contains kid, address, zip, nullable integer latitude, longitude, autoLatitudeLongitude, revision and outcome. Coordinates are millionths of degrees, not decimal degrees; latitude range ±90000000 and longitude ±180000000, with zero valid. Outcomes: Success, Unchanged, IncompleteAddress, ManualCoordinatesPreserved, ManualCoordinatesSaved, NoResult, TransientFailure, PermanentFailure, NotConfigured and Superseded. HTTP 200 can confirm a saved address even when geocoding fails; inspect outcome.
Errors use ProblemDetails with code: 400 invalid input/KID, 401 expired or changed session, 403 missing rights, 404 missing/invisible/deleted object, 409 stale revision (address-conflict), 503 storage unavailable. Reload on 409. After 503, timeout or a lost response, read back before retrying because the address may already be committed. The location overview has an address editor and a map above Units. Generated clients and downloadable packages are synchronized at version 0.4.2.
SetObjectCoordinateProvenance changes only AutoLatitudeLongitude: 0 (unknown), 1–12 (automatic lookup month), 13 (legacy pending), 20 (legacy failure), 30 (manual). Values 1–12 require a valid stored coordinate pair; 30 may be selected before coordinates exist. It returns ProvenanceSaved and never starts a lookup or schedules retries. canWrite is a display hint from the current permission snapshot; every write independently checks permissions.
The portal saves each address or postal-code field when it loses focus. Manual selects 30; Auto selects 13. Mode selection alone does not call Google. The map reads saved coordinates every ten seconds while the page is visible and refreshes if they change. These reads never initiate geocoding. Each address change allows at most one lookup when the source is not 30; success stores the UTC month. There are no background jobs or automatic retries after failure.
Windows app downloads
The unreleased 0.2.9 app source for Android, iPhone/iPad and Windows bundles the portal UI locally and calls the tenant's Portal API directly. Normal app use requires the API and internet, but does not require Portal Web to be running. External public portal links still require Portal Web. The current Windows correction does not rebuild Android/iOS packages. The new apps have not yet been signed for customer distribution or released.
The primary page is https://{tenant}.kombine.technology/download; this API's download page serves the same content. Beta uses the matching beta hosts. No login is required to download; installing the app grants no business access. Sign in normally inside the app.
GetPortalAppDownloadPage: GET /download returns HTML in all ten portal languages according to Accept-Language (English default; Danish fallback for individual missing translations). DownloadPortalWindowsAppInstaller: GET /download/windows/{architecture}/portal.appinstaller downloads the installation/update file. DownloadPortalWindowsPackage: GET /download/windows/{architecture}/{fileName} serves its exact versioned MSIX. Architecture is x64 or arm64.
Open the downloaded file with Windows App Installer. The signed package must be trusted on the device; WebView2 Runtime and internet access are required. Update checks at launch depend on Windows and device policy. 404 means no validated release for this site's tenant/environment/architecture, or an unknown filename. The page then shows unavailable downloads; there is no cross-tenant fallback. Installer/page responses use no-store; MSIX supports byte ranges (206) and ETag (304). Client request parameters cannot select another tenant. Signed customer packages and deployment artifact delivery have not yet been configured.
Unit documents: tables, CSV, XLS and SVG
Location and bank WashDoc history (new, unreleased)
GetLocationDocuments — GET /api/v1/locations/{locationKid}/documents uses the same active manager bearer, WashDoc tab, Location Read, Unit Read, site-bound grants and RetentionDays checks as bank document search. Only authorized, visible units are returned. Use date=yyyy-MM-dd to include the whole UTC date and earlier history back to 2000-01-01 (today by default on the location route). Repeat unitKids to select one or several canonical units in that location, up to 255; omitted means all visible units. A foreign or mismatched unit returns 400; a hidden/missing selected unit returns 404. Unit choices remain available even when unselected, and filtering happens before pagination.
GetBankDocuments accepts the same optional date, repeated unitKids, search, sort=activity|documentId and direction=asc|desc parameters. Without date, the existing from/through interval remains supported; combining date with from/through returns 400. Optional locationKid limits the bank list to one location. Repeat locationKids to select up to 1000 canonical location KIDs in the bank; all must be authorized and visible, and any selected units must belong to those locations. The same filter applies to GetBankDocumentsCount. search is an exact numeric Doc ID or canonical document KID in the selected scope. Unit names resolve localization placeholders using Accept-Language.
GET /api/v1/locations/LOCATION_KID/documents?date=2026-10-23&unitKids=UNIT_KID_1&unitKids=UNIT_KID_2&limit=25&offset=0
GET /api/v1/locations/LOCATION_KID/documents/count?date=2026-10-23&unitKids=UNIT_KID_1&unitKids=UNIT_KID_2
GET /api/v1/banks/BANK_KID/documents?date=2026-10-23&locationKid=LOCATION_KID
GET /api/v1/banks/BANK_KID/documents/count?date=2026-10-23
All requests need Authorization: Bearer ACCESS_TOKEN. GetLocationDocumentsCount and GetBankDocumentsCount return {count, from, through} using the same filters and authorization. Count distinct location/unit/document identities, not TagId alone. Fetch totals separately without traversing pages; a pending/failed count must not block rows. Lists return the existing BankDocumentPage shape (items, locations, units, from, through, offset, limit, hasMore). Paging is 1–100 rows (default 25), offsets 0–100000; reset offset after changing filters. No measurements are read. Existing 1000-location/5000-unit/35000-metadata-row bounds and twelve-second storage deadline remain; 422 means narrow scope, 503 means unavailable/busy. In Portal, bank and location WashDoc reuse the unit list/grid, one date cutoff, automatic lazy loading and independent loaded/total count. Generated clients and packages are deferred to beta preparation.
Use a canonical Doc KID containing the site's tenant, bank, location, unit and document TagId. A unit KID, numeric document ID or foreign tenant is not accepted. These operations read one known document; they do not discover document IDs.
Search documents
GetBankDocuments: GET /api/v1/banks/{bankKid}/documents discovers document KIDs for WashDoc1/2. It requires the same bearer, WashDoc Tab, Location Read, Unit Read and matching resource grants as the document endpoints. Only authorized, retention-visible locations and units appear in results and filter choices.
Optional locationKid and unitKid restrict the bank scope; a unit also selects its location. from/through are inclusive ISO 8601 timestamps with an explicit UTC offset, defaulting to the last 24 hours, with a maximum 31-day interval. Matching documents have a tagged Cycle setting inside that interval. lastActivityUtc means the latest matching Cycle, not the full start/end; the table provides full document bounds.
The JSON response contains items (kid, locationKid, unitKid, locationName, unitName, unitIconKid, unitType, lastActivityUtc), locations, units, effective from/through, offset, limit and hasMore. Units belong to the selected location scope. Read pages lazily with limit 1–100 (default 25) and offset 0–100000. Results sort by latest activity descending, then location/unit/document identity; live changes can shift pages, so reset offset to refresh. No total count or measurements are loaded by search.
400 means invalid filters; 401 sign in again; 403 no access; 404 selected object is hidden/missing; 422 narrow by location (at most 1000 locations, 5000 discoverable units, 35000 current-setting rows); 503 unavailable/busy, with no automatic retry loop. Searches have a 12-second storage deadline, two concurrent searches per API process and a one-second queue wait. Responses use no-store. The portal uses the shared list/grid described above, with authenticated Excel download and the interactive graph. List timestamps follow the browser time zone; date cutoffs use UTC.
WashDoc3: documents for one unit (unreleased)
GetUnitDocuments — GET /api/v1/units/{unitKid}/documents lists documents for exactly the canonical Unit KID in the site's tenant. Requires an active manager bearer session, specifically WashDoc3 (55), Location Read, Unit Read and a matching resource grant. Location and unit visibility follow RetentionDays before paging; hidden or missing objects return 404. The metadata and history reads are both restricted to this unit.
Use date=yyyy-MM-dd (UTC; defaults to today) to include documents from that entire day and earlier, back to 2000-01-01. There is no 31-day history-window limit for this exact-unit list. The previous from/through request parameters are removed and return 400; bank-wide searches retain their existing interval contract. Use sort=activity|documentId and direction=asc|desc (activity descending by default). Activity is the latest matching tagged Cycle at or before the selected day's end, returned as lastActivityUtc; it is not a document start/end timestamp. Document IDs sort numerically; activity ties use document identity. Use the item's canonical kid unchanged with the existing table, graph and download endpoints and their access checks.
Response: items uses the same item fields as GetBankDocuments; effective from is the UTC epoch and through is the selected day at 23:59:59.999Z. sort, direction, offset, limit and hasMore describe the page. No location/unit filter choices, total count or measurements are loaded. limit is 1–100 (default 25), offset 0–100000. Fetch more pages as needed with the same date and sort; reset offset after changes or refreshing because live changes can shift pages. A visible unit with no matches returns an empty items array.
GetUnitDocumentsCount — GET /api/v1/units/{unitKid}/documents/count?date=2026-10-21 separately returns {count, from, through} for the same date, tenant, unit and access rules. It counts distinct document identities directly without iterating pages or loading measurements. Start this request alongside the first page and show loaded rows while the total is pending; a failed count must not hide the list. Zero is a valid total. Counts and pages use separate snapshots, so a running machine can change the total; refresh both to reconcile. Keep date identical for both requests.
Errors use ProblemDetails with code: 400 invalid KID/time/sort/page, 401 sign in again, 403 missing permissions, 404 hidden/missing object, 422 oversized metadata, 503 document-unavailable or document-busy; retry manually. Reads have a 12-second storage deadline, at most two concurrent Unit list searches plus two independent counts per API process and a one-second queue wait. Responses use no-store. Generated clients and downloadable packages will be synchronized during beta preparation.
Unreleased: GetUnitDocumentCycleInfo — GET /api/v1/documents/{cycleKid}/cycle-info reads records tagged with the exact cycle under the same authorization as GetUnitDocumentTable. The JSON response has cycleKid, unitKid and entries with ms2000 and scalar unitType, machineType, machineProgramSet, version and numeric values represented as strings. Other CycleInfo properties are redacted; an empty list means none were recorded. A missing cycle returns 404. Invalid KID: 400; expired session: 401; denied scope: 403; oversized data: 422; unavailable storage: 503. Retry only transient errors and preserve previously downloaded data.
Operation
GET path
Output
GetUnitDocumentTable
/api/v1/documents/{cycleKid}/table
JSON table and metadata
GetUnitDocumentHtml
/api/v1/documents/{cycleKid}/table.html
Printable HTML table
DownloadUnitDocumentCsv
/api/v1/documents/{cycleKid}/table.csv
UTF-8 CSV
DownloadUnitDocumentXls
/api/v1/documents/{cycleKid}/table.xls
Excel 97–2003 binary workbook
GetUnitDocumentSvg
/api/v1/documents/{cycleKid}/graph.svg
SVG charts
GetUnitDocumentSvg2
/api/v1/documents/{cycleKid}/graph2.svg
Responsive WashDoc chart (unreleased)
GetUnitDocumentIcon
/api/v1/documents/{cycleKid}/icon.svg
Text-free visual preview (unreleased)
GetUnitDocumentGraph
/api/v1/documents/{cycleKid}/graph
Semantic chart JSON (unreleased)
GetUnitDocumentPng
/api/v1/documents/{cycleKid}/graph.png
Server-rendered PNG (unreleased)
GetUnitDocumentNeighbors
/api/v1/documents/{cycleKid}/neighbors
Previous and next numeric Doc ID (unreleased)
GetUnitDocumentNeighbors uses the same active manager bearer session, WashDoc1/2/3 tab, Location/Unit Read, tenant, resource scope and RetentionDays checks as full documents. It returns {previous, next}; each existing neighbor has a canonical kid and lastActivityUtc (latest tagged Cycle timestamp). Missing neighbors are null and their navigation widgets should be hidden. Doc IDs count down: previous is the nearest higher numeric Doc ID (older document), and next is the nearest lower numeric Doc ID (newer document). The search covers this exact unit's full stored history, skipping gaps and ignoring list dates, ordering and filters. No measurement data is loaded. Responses are uncached and bounded by a 12-second storage deadline. Handle 400 by correcting the document KID, 401/403 by checking session/access, 404 as a missing/hidden location, unit or selected document, and 503 with a manual retry. Client package updates are deferred to beta preparation.
GetUnitDocumentGraph and GetUnitDocumentPng accept the canonical document KID, optional states/settings selection and the same manager bearer session, WashDoc tab, Location/Unit Read, tenant/scope/retention permissions as the other full document endpoints. No client-supplied chart configuration is required. Both reuse the bounded graph2 data acquisition, exact cycle resolution and legacy edge context; they are not public widget URLs.
Graph JSON includes cycleKid, unitKid, unitName, finished, graph bounds fromMs2000/toMs2000, and exact nullable cycle bounds startedMs2000/endedMs2000. All timestamps are UTC milliseconds since 2000-01-01. series contains stable kind/name/localization, label, semantic group, role (measurement or target), optional unit, step and sparse points. Each point has ms2000, nullable finite value, isCalculated, isEdge and optional unit. Stored nulls break a curve; absent points do not. No resampling, smoothing, visual coordinate transforms or quantity inference is applied. Use only actual non-edge points for nearest-sample tooltips; retain edge points for clipped drawing. JSON scale values remain in their recorded units; a mixed-unit series has null series.unit and must not be drawn on an incorrectly shared scale. Bare legacy Level has no assumed liters or physical unit, except for the documented type-specific temperature alias below.
presentation contains the trusted original decoded unitType, kind (washer, dryer, dosing, energy or generic) and preferred groupOrder. Draw only observed groups, in that order, then retain additional observed groups. PNG and widget previews use the same type profile. For Alliance dryers 19/29/30 only, historical Level represents the second temperature: its group becomes temperature2, label/localization use Temperature2, and bare values use °C. LevelTarget/LevelUnfiltered remain separate legacyLevel measurements with unknown units. Bare Humidity uses % for these three types only. For QW washers 15/16/17/25/31, bare Spin values 0–3 are ordinal steps with no rpm unit; explicit rotation-scale JSON retains its recorded units. Unknown units are never guessed. Numeric humidity, voltage, current and frequency are supported when actually present; unavailable groups do not create empty bands. The small widget shows at most four prioritized numeric curves; a document containing only dosing events still has no numeric widget preview.
Legacy eState.Process (138) is read from Live and States history in the same bounded document window, including older untagged samples. An event has kind="state", name="Process" and retains the original eProcess byte: 1 Prewash, 2 Mainwash, 3 Rinse1, 4 Rinse2, 5 Rinsefinal, 6 Spin, 7 Done. These codes are independent of Cycle and CycleSub. Shared equivalent phase translations provide the label/localization key without changing the stored code; unknown valid byte codes remain explicit. Only actual in-window changes become phase markers and historical hover observations, in both browser and PNG rendering. Duplicate unchanged values are omitted from the marker layer while complete stored events remain available. Process.Done does not replace tagged Cycle/Doc-ID boundary resolution.
events contains stored Cycle/Process/CycleSub/Error codes with exact timestamps, enum names, shared localization keys and translated labels where available. signals contains InOutletHeat changes: normally heat bit 32, inlet bits 1/2/4/8, outlet bit 16. Alliance dryers 19/29/30 instead use heat bits 32|64 and airflow bit 16; inlet/outlet are null. Airflow is null for other types. Null flags/booleans mean unknown or inapplicable, not off; a known change holds until the next stored change. dosing contains SoapInfo product names and recorded nullable durationMs, volumeMl, massGrams, process and step. Both legacy tab-separated forms and packed amount/duration words are supported; missing quantities remain null. Internal source tags are never published.
The PNG endpoint renders the same semantic data with the local Chart.js renderer on an opaque white background, suitable for email attachments/inline images. It requires no open browser and makes no external chart-service request. PNG rendering is bounded; unavailable renderer returns 503 document-renderer-unavailable. Both endpoints reauthorize every request and use no-store; no incremental HTTP streaming is implemented. Existing limits remain: at most 16 numeric series, 31 days, 50,000 source samples, 500,000 cells and a 12-second storage deadline. Handle 400 by correcting KID/selection; 401/403 by checking login/access; 404 as missing/hidden; 422 by narrowing selection; 503 by a manual retry. Existing SVG/widget routes remain available. Client package regeneration is deferred to beta preparation.
GetUnitDocumentSvg2 uses the same bearer authentication, tenant/scope/retention checks and optional states/settings selection. Measurement bands share scales with dashed targets; stored Cycle/Process/CycleSub/Error events are marked. Doc ID selects tagged cycle history: PREPARING starts the cycle, first DONE ends it, or last tagged measurements bound an unfinished cycle. The graph adds a one-minute margin and rounds duration up to the next minute. Legacy untagged measurements are read for the exact unit in that bounded window. Nearest edge samples for observed fields are searched at most one hour beyond it and clipped; no interpolation or fabricated samples. Known legacy measurement JSON is interpreted without changing original text or converting units. At most 16 numeric series; 422 means no numeric measurements or too many series. SVG fills both viewport dimensions while text and strokes remain stable; times use UTC. The original graph remains available. Both reauthorize before separate private completed-document caches and return no-store; unfinished graphs are fresh. Handle 401/403 by checking login/access, 400 by correcting KID/fields, 404 as missing/hidden, 422 by narrowing selection and 503 by retrying manually.
Send the manager bearer token on every request. Requires at least one of WashDoc1 (54), WashDoc3 (55), WashDoc2 (75), Location Read, Unit Read and a matching tenant/bank/location grant. Location and unit deletion follow RetentionDays. Authorization is reapplied before every SVG cache lookup, using the normal bounded manager/location/unit snapshots.
historicalMeasurements=true adds a fixed document-only whitelist of temperature, level, spin, energy/power, remaining-time and process-event states, independent of today's unit model. Default false for tables; graph2 and icon enable it automatically. It adds no settings or credential access and does not change saved unit types. Existing selection and document limits still apply. GetUnitDocumentIcon reuses the same authorized data/window and completed graph cache, renders only the first available curve in graph-picker order as a transparent, monochrome 24-unit line icon with currentColor and preserved local peaks. It has no fill, gradient, text or axes and is not a reading scale. Fetch visible icons lazily with bounded concurrency; use a generic document placeholder for 422 or failed reads. Example: replace graph2.svg with icon.svg in the bearer request above and create an image blob URL.
Optional states and settings are comma-separated exact enum names, for example states=Temperature,Level&settings=Cycle on a supported washer. Omit a category to select all its permitted fields; an empty value selects none. By default, only visible current-unit catalog bindings are allowed. Credentials, hidden fields and fields belonging to other objects are never read. Unknown unit types return 422. Enum identifiers and export labels are language independent; presentation labels are currently English.
Values and downloads
JSON contains cycleKid, unitKid, unitName, finished, document bounds in MS2000, columns and rows. Cells follow column order. A null cell means absent; a cell with null text/value is a stored null. text preserves the decoded original. value is a finite double when available; use text for exact large numbers. No endpoint interpolates or rounds table values.
Only columns with data anywhere in the complete authorized document are returned, including when explicitly selected. A column is empty when every cell has no numeric value and its text is null, empty or whitespace-only. Numeric zero, false and nonempty text are data. Remaining columns retain their order, and each row's cells follows that returned order; row timestamps are unchanged. An entirely empty selection has columns: [] and empty cell arrays. Build the mapping from columns on every response instead of assuming fixed positions or the presence of every requested field. CSV, XLS, HTML and the portal's Excel download use this same filtered table.
CSV uses a UTF-8 BOM, commas, quoted cells and CRLF. Potential formulas in nonnumeric text receive a leading apostrophe. CSV cannot distinguish missing/null/empty cells. XLS is genuine BIFF8, with text written as strings rather than formulas; more than 15 digits and noncanonical numeric formatting stay as text. Both include MS2000 and ISO UTC columns. HTML can be printed using the browser. PDF is not provided.
Graphs and completed-data cache
SVG is rendered directly with .NET XML, with no third-party chart library, scripts or external assets. Each numeric series has a separate labelled scale. Enum/boolean values use steps; explicit null/invalid measurements break a line. Sparse timestamps from other series do not. Select at most 16 numeric series; width accepts 480–2400 (default 1200).
Only a document with a terminal Cycle and an InSync timestamp at least two minutes beyond its full end is finished=true. Only finished SVGs are cached, on private disk outside wwwroot, for at most 24 hours. Keys include tenant-bound KID, unit type/name, ordered fields, width and renderer version. The cache holds at most 128 MiB/256 files and falls back to fresh rendering on cache I/O failure. In-progress SVGs and all tables/downloads are uncached. All HTTP responses use Cache-Control: no-store. X-Document-Complete reports completion; that header and Content-Disposition are available to configured CORS clients. An SVG URL requires bearer authentication; fetch it before creating an image blob URL.
One document, up to 31 days, 128 columns, 50,000 source samples, 500,000 cells, 16,384 characters per value and 8 million characters overall. Storage has a 12-second deadline. At most two exports/renders run concurrently per API process, with a one-second queue wait. Failures never return a successful partial document.
When a field category is omitted, its authorized catalog is used as a bounded candidate list; only fields encountered in the document count toward the 128-column limit. Large machine catalogs therefore do not fail solely because many settings have no document data. Explicit field selections remain limited to 128 fields in total. Tenant, permission and field-visibility checks still apply.
400: invalid KID/field selection/width. 401: sign in again. 403: missing access. 404: missing or retention-hidden object/document. 422: unsupported unit type, document too large, no numeric graph data or more than 16 series; use fewer fields when applicable. 503: storage unavailable or document-busy; show unavailable and avoid automatic retry loops. Errors use ProblemDetails with a stable code. Generated clients and downloadable packages are synchronized in version 0.4.2.
Getting started: Find the API address → log in as a manager → request /api/v1/session/me.
Available now: API availability, the public active-user count, and the signed-in manager’s name, icon, Tabs, bank/location access, and operation permissions. These are the data displayed on the portal’s current overview. Users2 lists, resident editing, activation letters and CSV export are available through the operations documented below. Other Tabs may still lack business operations. A permitted Tab does not mean its business functionality already has an API endpoint.
Use the tenant API domain: https://api.{name}.kombine.technology in production or https://beta.api.{name}.kombine.technology in beta. Names: team, electrolux, portal, washco, finelec and nortec. Each hostname is bound to server-configured tenancy. KIDs, form fields and forwarded host headers cannot change the tenant. Tokens apply only to their tenant and environment; log in separately when switching. Unknown hosts return HTTP 400. Beta currently uses the same tenant databases as production.
Resident receipts — GetUserReceipts (unreleased)
GET /api/v1/users/{userKid}/receipts uses the existing manager bearer session. Requires an active account, Users2, User Read and access to the resident's entire bank. A location-only grant is insufficient. The canonical user KID must belong to this API's configured tenant. Permissions are checked on every page through the normal manager snapshot (at most 60 seconds old); missing or retention-hidden residents are indistinguishable.
API='https://localhost:20332'
USER_KID='A6Q3CoAC1b41Dh'
curl --get "$API/api/v1/users/$USER_KID/receipts" \
-H "Authorization: Bearer $TOKEN" --data-urlencode 'offset=0'
# For an older page, use nextOffset and revision from the previous response:
curl --get "$API/api/v1/users/$USER_KID/receipts" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "offset=$NEXT_OFFSET" --data-urlencode "revision=$REVISION"
The response contains userKid, revision, items[], nullable nextOffset and periodCount=24. Each page has at most 20 whole receipts; offsets count receipts, not lines. Start at zero without a revision. Stop at nextOffset:null. Load only when the receipt section or its end becomes visible, with one request in flight; do not poll the whole history.
Each receipt contains key, local date, nullable locationKid, locationName, period (zero is current), provisional, kind (Purchase, Payment, Discount, TransferToRent), nullable currency, totalMinor, nullable vatMinor, balanceAfterMinor and lines[]. Lines provide nullable transaction kid, offset-aware occurredAt, nullable unitKid, unitName, all description texts[], amountMinor and calculated. Calculated settlement adjustments have no stored transaction KID.
Money is signed 64-bit minor units. A negative stored posting becomes a positive receipt amount; refunds retain the opposite sign. Keep currencies separate without conversion; unknown currency stays null. Receipt balances exclude unused current-period discount, unlike the current balance header. Discount applies to DKK only. VAT is included in the total and is returned only for cash-bank purchases with a valid configured rate; null is unknown/not applicable. Groups are separated by local day, location, kind, period and currency. Zero-total documents and Month lines are omitted.
History covers period zero and the latest 24 stored period numbers, further limited by accounting/surveillance retention. Deleted-resident visibility follows the manager's RetentionDays. Each request builds a bounded read-only snapshot: 12-second storage deadline, two concurrent reads per API process, at most 50,000 postings, 8 MiB of stored text and 1,000 documents per receipt. SQL uses Log tables only. There are no refund, payment, export or mutation operations in this endpoint. Generated clients are updated at beta release.
Errors: 400 invalid-user/invalid-page; 401 (may have no JSON body); 403 forbidden; 404 not-found; 409 receipts-changed; 503 receipts-too-large/storage-busy/storage-timeout/storage-unavailable. A 409 means discard loaded pages and restart at zero: never combine different revisions. On 401/403/404 clear the history and stop loading. On 503 show an error and offer manual retry, never fabricated zero totals. No oversized or failed result is silently truncated.
Live logs
GetLiveLogs — GET /api/v1/diagnostics/live-logs uses your reusable manager bearer session. Requires an active manager, Logs1, Managers Read and a whole-tenant KID grant. A bank-only grant is insufficient. The site selects the tenant; no tenant or server selector is accepted.
The response contains tenantKid, fetchedAtUtc, refreshAfterSeconds and three servers cards: portal-api, equipment-api, portal-web. Each card has errorCode (null on success) and events, newest first. Events include timestamp, level, message template, category and optional statusCode, elapsedMilliseconds, bankId, userIds and traceId. Numeric bank/user IDs are diagnostic values, not resource selectors.
Poll no faster than every 3 seconds. Every request rechecks access before reading cached data. 401 means invalid/revoked session; 403 means missing-logs-tab, missing-managers-read or missing-tenant-access; 503 means authorization storage is unavailable. Stop polling and clear displayed data on 401/403. Per-card errors are live-logs-not-configured or live-logs-unavailable; other cards remain usable.
Each process retains at most 100 sanitized events for 15 minutes, cleared at restart. Application Information events and all Warning-or-higher events are captured. Only approved diagnostic fields and the current assistant question are retained from message arguments; exception text is omitted. Empty cards can mean no recent events. This is in-memory diagnostics, not Logz.io history or an audit trail. Multiple replicas retain separate buffers; aggregation across replicas is not supported.
Chat question events additionally include optional question (up to 2000 characters). Authorized live-log viewers can see this text. Render it as plain text, never as HTML; the portal displays it in bold in place of the message placeholder.
Events also expose optional fields, a map of sanitized structured values. Substitute matching message placeholders as encoded text; the portal displays values in bold. Unknown or filtered placeholders remain unchanged. Existing event fields are retained.
When continuous DO-to-Logz.io forwarding is enabled, this endpoint reads the recent in-memory collector buffer. The buffer retains all received lines; only lines with a recognized Warning-or-higher severity are eligible for shipping to Logz.io. Lines without a recognized severity are omitted from shipping. Delivery runs independently of open pages. A visible line confirms receipt from DigitalOcean, not acceptance by Logz.io. Logs1 also displays this panel; permissions remain unchanged. Forwarding is best effort, with possible gaps and duplicates after interruptions.
DigitalOcean runtime logs
GetHostingLogs: GET /api/v1/hosting/logs. Requires a manager bearer session, Logs1, Managers Read and whole-tenant access. Operator policy explicitly permits logs across tenants for the configured app. Hosting1 alone is insufficient.
environment: beta/production; application: portal-api/equipment-api/portal-web. Response: environment, application, fetchedAtUtc, lines (up to 100 plain-text lines), truncated. Poll at most every 10 seconds. Content is bounded to 256 KiB; successes and failures are cached for 10 seconds. Snapshots may overlap and are not a complete history. Render as text, never HTML. Pause freezes display while access checks continue; hiding/leaving clears data. No MySQL, build, deploy or crash logs.
400 invalid-hosting-selection; 401 invalid session; 403 missing-logs-tab, missing-managers-read or missing-tenant-access; 503 hosting-not-configured or hosting-unavailable. Clear on error and stop on 401/403. Provider credentials and signed URLs stay on the server. Access is rechecked before cache hits using the manager snapshot (up to 60 seconds old). Included in client packages 0.4.2; availability requires operator configuration.
Hosting1 — hosting metrics (unreleased)
GetHostingMetrics: GET /api/v1/hosting/metrics?environment=beta&application=portal-api&hours=24. Reuse the manager bearer session. Requires an active account, Hosting1 (81), Managers Read and a whole-tenant KID grant for the API site. Every call, including a metric cache hit, checks the manager snapshot, which is at most 60 seconds old. These are shared infrastructure measurements across customers, not the caller's individual tenant consumption.
environment: beta or production (default beta). application: portal-api, equipment-api, portal-web or mysql (default portal-api). hours: 1, 6 or 24 (default 24). Resource mappings are controlled by the API site; clients cannot supply a provider ID, tenant or URL. Beta and production can map to the same database.
The response contains environment, application, fromUtc, toUtc, fetchedAtUtc, refreshAfterSeconds, metrics, bandwidth. Each metric has name, unit, series, errorCode. Each series has component, instance, points; each point has timestampUtc and nullable numeric value. App metrics are cpu/memory in percent and restarts in count. Keep separate instances separate: restarts are the provider's series, not a calculated total for the selected window. MySQL returns cpu, memory, disk in percent using the provider's cluster average and connections (connected MySQL threads) in count. Missing provider labels use a numeric series label; it is display text, not a persistent object identifier.
For apps, bandwidth has dateUtc, bytes, errorCode. It always describes yesterday in UTC, independently of hours. Bytes is an unsigned decimal string, preserving 64-bit precision, or null when absent. For MySQL, bandwidth is null. An empty series or a null sample means missing data, never zero. Sample timestamps may lag; fetchedAtUtc identifies the snapshot, not measurement freshness.
Check every errorCode: individual failures return hosting-source-unavailable with no series (or null bytes); other measurements remain in HTTP 200. If all sources fail, the API returns 503 hosting-unavailable. Disabled or incomplete integration returns 503 hosting-not-configured. Other errors: 400 invalid-hosting-selection; 401 requires login; 403 missing-hosting-tab, missing-managers-read or missing-tenant-access. The listed 400/403/503 application errors use ProblemDetails with code. Malformed query types use standard model-validation errors; 401 can have an empty body. Provider error text and credentials are never returned.
Honor refreshAfterSeconds (60). Results and failed lookups are cached for one minute; browser responses are no-store. Pause polling while hidden, prevent overlapping requests, and clear displayed data after 401/403. Partial/empty data is not evidence of healthy infrastructure. Only the documented app and Managed MySQL metrics are available; the operation does not query SQL, change resources, expose logs or provide customer-specific billing. Generated clients and downloads will be synchronized at beta release.
TenantStatus1 — operational alerts
GetTenantStatus: GET /api/v1/tenant/status?limit=200. Reuse the manager bearer session. Requires TenantStatus1 (80), Bank Read, Location Read, Unit Read and a matching tenant/bank/location KID grant. Tenant navigation does not grant tenant-wide data access. The site selects the tenant; scope and RetentionDays for bank, location and unit are applied before limiting rows. Enabled must be exactly 1 at the location. Missing Deleted means zero; invalid or future deletions are hidden.
Offline uses the tenant Alive table (explicitly approved): UnitId = MainId, Cluster other than Test, contact between 100 days ago and one hour ago for Cash, or one day ago for other nonempty BankType values, including boundaries. AutoOutOfOrder uses Log24 OutOfOrder = AutoOutOfOrder, excludes StartSMS_60 and TimeSMS_61 and reads a positive integer error Id from the AutoOutOfOrder state JSON. Only the original packed UnitType determines type, using (value >> 1) & 255. UnitType2 is never an override or fallback. Missing/invalid types are excluded from that lookup.
Response: measuredAtUtc, refreshAfterSeconds (30), sources and items. Each source has kind, count, hasMore, errorCode. Each item has kind, kid, bankKid, locationKid, bankName, locationName, unitName, computerName, bankType, unitType, errorId, timestampUtc, iconKid, bankIconKid, locationIconKid. KIDs are canonical. unitType/errorId are nullable integers. timestampUtc means last contact for Offline or the OutOfOrder setting timestamp. Send Accept-Language for localized name placeholders. Items sort by timestamp descending, then kind and KID; a unit may have both alerts.
bankIconKid and locationIconKid contain the configured bank/location icons from Log24, with the object number encoded in Kid.Text by the API. Missing or invalid icon settings use bank_building/house. Render these values unchanged with GET /api/v1/icon/{iconSet}/{iconKid}.svg; for example, "/api/v1/icon/g/" + encodeURIComponent(item.locationIconKid) + ".svg". Use bankKid/locationKid for object links and workspace shortcuts. ComputerName, bankType and unitType remain available for supplementary tooltips; icons and shortcuts never grant access.
Lookups run in parallel on separate connections with a 12-second request deadline. A failed source returns status-source-unavailable, count 0 and no items while successful sources remain in HTTP 200. Always inspect sources; a partial result does not mean healthy. All sources failing returns 503 tenant-status-unavailable. 400 invalid-limit; 401 requires login; 403 codes: missing-status-tab, missing-bank-read, missing-location-read, missing-unit-read, missing-resource-access. Errors use ProblemDetails/code. Results are no-store.
Limits: 1–1000 rows per source, default 200. hasMore explicitly means only the newest rows are included; no cursor or historical export is provided. Accept additional kinds in future. Refresh no faster than every 30 seconds, stop while hidden and avoid overlapping requests. Generated clients and downloadable packages are synchronized in version 0.4.2.
const response = await fetch(apiBase + '/api/v1/tenant/status?limit=200', {
headers: { Authorization: 'Bearer ' + accessToken, 'Accept-Language': 'en-GB' }
});
if (!response.ok) throw new Error('HTTP ' + response.status);
const status = await response.json();
for (const source of status.sources) {
if (source.errorCode || source.hasMore) console.warn(source.kind, source);
}
console.table(status.items);
Lazy pages — GetTenantStatusPage (unreleased)
Offline laundries — single-file example selects kind=Offline after reading every page, groups terminals by canonical locationKid and separates bankType=Credit from Cash; other types remain separate. It shares the examples' manager login and local-origin support. Cash requires at least one hour since last contact, other nonempty types at least one day, within the API's 100-day window. Cards and terminal lists show the most recent contact first within each bank type. Each card shows the most recent contact among its returned terminals; it does not imply that every terminal at that laundry is offline. A failed Offline source retains a visibly stale snapshot, and hasMore warns that the 1,000-terminal limit can omit laundries or terminals.
The examples directory provides shared API login and logout above the list. Log in there once to use the manager examples on this API address in the same browser; logout also clears their open tabs.
Automatically out of order — single-file example displays cards from this endpoint after following all cursors and selecting AutoOutOfOrder. It shares the Cycles example's remembered manager session on the same API origin and browser; logging out clears that shared login, and API keys are never stored. Save the HTML and serve it at http://localhost:8080 or http://127.0.0.1:8080 to use it locally. Only these exact local origins are enabled for this paged read, login and renewal; bearer authentication, TenantStatus1 (80), Bank/Location/Unit Read and resource grants remain required. It refreshes every 30 seconds while visible, labels capped or failed results, and retains an explicitly stale snapshot during temporary failures. An alert with no error code remains visible.
GET /api/v1/tenant/status/page?pageSize=25 provides the same authorized alerts in pages of 1–100 rows (default 25). The existing GetTenantStatus contract is unchanged. The response has status (the status envelope above, with only this page in items), offset, totalCount, previousCursor, nextCursor. Source counts cover the bounded snapshot, not only the page. The API reads up to 1,000 rows per source once; hasMore still warns of truncation. Later pages reuse this snapshot without rerunning the lookups.
Send a returned cursor unchanged, keeping pageSize and Accept-Language unchanged. Every page rechecks the active manager, Tab and operation permissions. Cursors are bound to manager, tenant, credential stamp, resource scope, RetentionDays and language; they never grant access. Snapshots expire after two minutes and can be evicted sooner. HTTP 400 means invalid paging input/cursor; 409 means changed context; 410 means expired/evicted snapshot. For 409/410 discard the cursor and request a fresh page; 401/403/503 have the meanings above. Responses are no-store.
Refresh without a cursor every 30 seconds. Optional anchor=Offline:UNIT_KID starts at that authorized row; offset=50 (0–1999) is the clamped fallback if the anchor has disappeared. Do not combine cursor with anchor/offset. This allows refreshing around the visible row. The portal keeps at most five 25-row chunks and requests earlier/later pages when scrolling. No historical export or unlimited scan is provided.
Select Public v1 (no login) in Swagger for anonymous status, statistics and the purchase map. Download its contract as Public OpenAPI JSON. Portal integrations v1 contains manager login and manager operations. This split does not change routes, operation IDs or access control. Clients generating public calls from the previously combined v1 document must now also import the Public document.
Purchases in the last hour
GET /api/v1/public/statistics/purchases requires no login. Its Swagger operation is GetPublicPurchases; the JavaScript client provides client.getPurchases().
Counts rows in the site's A{tenant}.Log1Hour using UserId >= eUserId.Users AND UserId <= eUserId.Guest AND Text NOT LIKE '%E' AND Amount < 0. These are purchases, not distinct customers. E matching follows the table's collation. The shared enum defines the inclusive user range, currently 1001–999999999, including guest purchases. No bank filter is added. The response contains currencies: [{currency, count, amount}], with one group per currency and amount = -SUM(Amount)/100 in major currency units within that group. A missing currency remains null in its own group. The top-level count equals the sum of group counts. No purchases returns count: 0 and currencies: []. There is no combined monetary total or currency conversion.
The database maintains Log1Hour with cleanup every minute. This operation uses its contents exactly as the agreed SQL does, so the actual window depends on that cleanup. sinceUtc is the nominal start one hour before measuredAtUtc; lookbackHours is 1. tenantKid identifies the site and count is the total. Clients cannot override the tenant or filters.
Results are cached for one minute per API instance. The card refreshes automatically every minute while the page is open. Concurrent requests share one database query. HTTP 503 with Retry-After: 60 means unavailable, not zero. This anonymous widget read permits GET from any origin without credentials; protected operations keep the exact-origin CORS policy.
const response = await fetch('https://api.team.kombine.technology/api/v1/public/statistics/purchases');
if (!response.ok) throw new Error('HTTP ' + response.status);
const purchases = await response.json();
console.log(purchases.count);
for (const group of purchases.currencies) {
console.log(group.currency, group.count, group.amount);
}
Unreleased contract change: replace reads of the former top-level amount and currency with iteration over currencies. See the changelog. Packaged clients will be synchronized during beta release preparation.
Purchase chart as SVG
GetPublicPurchasesChart — GET /api/v1/public/statistics/purchases/chart/{color}.svg returns image/svg+xml without login. The API generates a transparent 320 × 80 sparkline that spans the card's inner width, showing only a line without area fill, visible numbers, axis labels or point markers. The final segment ends in an open arrowhead aligned with that segment; each wing is half the segment's length and uses the same stroke and color, without fill. Twelve five-minute purchase counts are spaced evenly from the left edge to the right edge, oldest first. The vertical scale follows the observed minimum and maximum. A constant series, including all zeroes, draws a centered flat line. Exact counts remain in the SVG description for accessibility. Intervals divide the exact rolling UTC hour from sinceUtc inclusive to measuredAtUtc exclusive, using each row's MS2000; they are not rounded to clock boundaries. Empty intervals count as zero. The chart counts purchases across currencies, not money, and uses the same purchase filters and one-minute snapshot as the JSON response. The JSON totals still include all retained qualifying Log1Hour rows, so their count can differ from the chart's sum when rows outside the chart window remain in the table.
The root svg element exposes data-counts: twelve comma-separated nonnegative integers in invariant format without grouping separators, oldest first. These are the same values used for the line and SVG description. When rendering with img, read the attribute from the fetched SVG and include the values in a localized alt description. Reuse that SVG response for the image and text; no additional data request is needed.
The required color path parameter accepts a three- or six-digit RGB hex value without #, such as 258623, or a supported SVG color name such as green. It only changes presentation. Tenant, dates, interval length and purchase filters cannot be overridden. The response is Cache-Control: no-store with X-Content-Type-Options: nosniff; refresh once a minute. Invalid color: HTTP 400 with ProblemDetails code invalid-purchase-chart-color. Unavailable data: HTTP 503 with code purchase-statistics-unavailable and Retry-After: 60; retain the previous chart or show unavailable, never a fabricated zero.
<img src="https://api.team.kombine.technology/api/v1/public/statistics/purchases/chart/258623.svg"
width="320" height="80" alt="Number of purchases per 5 minutes over the last hour.">
The SVG contains aggregated counts only. No transaction details, account identifiers or manager permissions are exposed. This endpoint is unreleased; generated clients will be synchronized during beta preparation.
Public data without login
GET /api/v1/public/statistics/active-users — Active-user count for the site's tenant. Swagger: Public → GetPublicActiveUsers.
The count includes distinct bank/user pairs in the tenant's current Log7, with user IDs 1001 through 99999 inclusive or the guest ID 999999999 (eUserId.Guest), bank ID at least 1000, and MS2000 strictly newer than 100 days before the UTC measurement time. Multiple rows for one pair count once; the same user ID in two banks counts twice. Activity means a recent Log7 record, not necessarily a login. User Enabled and Deleted settings are not additional filters.
This aggregate is public and independent of manager permissions. No individual accounts or per-bank counts are exposed. The site chooses the tenant; this operation accepts no KID, date window, or other filters.
tenantKid identifies the site's tenant, count is the total, lookbackDays is 100, sinceUtc is the exclusive cutoff, and measuredAtUtc is the measurement time. Results are cached for up to 5 minutes per API instance. Concurrent visitors share one query, with no background polling. Database failures return HTTP 503 and Retry-After: 60; display unavailable, not zero. A successful response with count 0 means a genuine zero.
const response = await fetch('https://api.team.kombine.technology/api/v1/public/statistics/active-users');
if (!response.ok) throw new Error('HTTP ' + response.status);
const statistics = await response.json();
console.log(statistics.count, statistics.measuredAtUtc);
The JavaScript client also provides client.getActiveUsers(). This anonymous widget read allows GET from external origins without credentials. Authenticated operations still require the configured exact origin.
Kombine logos — local SVG
Public, font-independent versions of the three original Kombine logos. Choose Public v1 (no login) in Swagger. No login, business KID, Tab, permission or database access is required. Rendering uses .NET XML, the original symbol geometry and locally embedded wordmark outlines, including the registered mark. No third-party graphics components, installed fonts, scripts or remote assets.
Artwork
Path prefix
Operation ID
Proportions
Symbol
/api/v1/logos/kombine
GetKombineLogo
1:1
Name only
/api/v1/logos/kombine-text
GetKombineText
590:111
Symbol and name
/api/v1/logos/kombine-logo-text
GetKombineLogoText
5:1
Each prefix has three forms: /{color}.svg, /{color}/{width}.svg and /{color}/{background}/{width}.svg. Operation IDs for the latter two append Sized and WithBackground. All parameters are path segments; no query string. SVG only, no raster-format fallback.
Symbol parts: Use /api/v1/logos/kombine/{parts}/{color}.svg, optionally followed by width or background/width before .svg. Operations: GetKombineLogoParts, GetKombineLogoPartsSized and GetKombineLogoPartsWithBackground. Parts accepts 1–4 letters N/E/S/W, case-insensitively, including combinations such as WE. N/S are vertical bars; W/E each include a horizontal bar and curved path. The original square viewBox is preserved. Invalid parts return 400 with invalid-logo-parameters. All parameters are path segments. Standard symbol routes return the complete symbol. Public access, colors, sizing and caching are unchanged. Unreleased; client regeneration is deferred to beta. Server disk cache preserves the URL path and SVG filename under a renderer/asset revision directory. Subsequent requests read the saved file, also after restart, until expiry or eviction.
GET /api/v1/logos/kombine/W/black.svg
GET /api/v1/logos/kombine/E/black.svg
GET /api/v1/logos/kombine/N/black.svg
GET /api/v1/logos/kombine/S/black.svg
GET /api/v1/logos/kombine/NS/black.svg
GET /api/v1/logos/kombine/WE/white/174d61/128.svg
GET /api/v1/logos/kombine/black.svg
GET /api/v1/logos/kombine-text/black/512.svg
GET /api/v1/logos/kombine-logo-text/white/174d61/512.svg
Colors accept 3/6-digit RGB hex without #, exact eColor names, standard color names or transparent, case-insensitively. Unknown names are rejected, not guessed. Without a width segment, the SVG has no fixed width/height: its viewBox and preserveAspectRatio="xMidYMid meet" fit and center the entire logo in the available viewport without cropping or stretching. Explicit width is an integer from 16–4096 pixels; height follows the original proportions and can be fractional. Use a sized URL or dimensions on the embedding element for a fixed size. The background is transparent unless explicitly supplied. Unlike the old raster-only background handling, an explicit background is painted directly into the SVG. Include alternative text when embedding the image.
All inputs describe a complete image. First requests render and atomically save to private disk outside wwwroot; repeated variants reuse files, including after restart if the disk remains. The cache keeps at most 512 variants/32 MiB for 24 hours; keys distinguish artwork, normalized colors, width, renderer version and the embedded asset hash. Cache I/O failure falls back to fresh rendering. Responses use image/svg+xml, a public 600-second browser cache and ETag/If-None-Match with 304.
Errors: 400 for invalid colors or width, without silent clamping. Validated parameters return code: invalid-logo-parameters; malformed integers use standard validation ProblemDetails. 404 for unknown routes/formats such as PNG. 429 when 16 logo requests are already running; retry with backoff. These are new endpoints, not aliases of KombineLogo1/KombineText1/KombineLogoText1. Generated clients and downloadable packages are synchronized in version 0.4.2.
GetLinearGradient and GetLinearGradientSized render a linear gradient over the entire canvas. Select Public v1 (no login), tag Gradients, in Swagger. Public presentation only: no login, KID, permissions or database access.
colors: 2–4 hyphen-separated colors, evenly spaced; 3/6-digit RGB hex without #, exact eColor names, standard named colors or transparent (case-insensitive). angle: finite degrees clockwise; 0 = left to right, 90 = top to bottom, 180 = right to left, 270 = bottom to top. Use a dot for decimals. Negative angles and full turns normalize modulo 360. Dimensions default to 200 × 200 or accept 16–4096 pixels each. Geometry retains the angle at the requested dimensions and spans the full rectangle.
SVG only, all inputs in the path; no scripts or external assets. Supply alternative text when embedding. Private disk cache: 24 hours, at most 512 variants/32 MiB; I/O failures fall back to rendering. HTTP: image/svg+xml, public cache for 600 seconds, ETag/If-None-Match with 304. Errors: 400 ProblemDetails for invalid inputs (invalid-gradient-parameters for rendering validation; malformed numbers use standard validation), 404 for unsupported formats/routes, 429 when 16 concurrent gradient requests are active (retry with backoff). Generated clients and packages will be synchronized at the next beta release.
GET /api/v1/gradients/linear/{colors}/{angle}.svg
GET /api/v1/gradients/linear/{colors}/{angle}/{width}x{height}.svg
GET /api/v1/gradients/linear/22aa88-ffcc33/45/800x400.svg
curl --fail --output gradient.svg "$TENANT_API/api/v1/gradients/linear/22aa88-ffcc33/45/800x400.svg"
Circles and progress — SVG
Three public visuals replace the rendering functions of CircleGradient1, CircleProgress1 and CircleRunning1. Select Public v1 (no login) in Swagger. They render only the supplied colors and percentage, with no login, business KID, permission requirement or database call. They do not read equipment status or calculate progress. Rendering uses .NET XML and local geometry; no third-party graphics components, external assets or scripts.
Visual
Operation ID
With dimensions
Angular gradient background
GetCircleGradient
GetCircleGradientSized
Percentage circle
GetCircleProgress
GetCircleProgressSized
Running indicator
GetCircleRunning
GetCircleRunningSized
GET /api/v1/circles/gradient/{colors}.svg
GET /api/v1/circles/gradient/{colors}/{width}x{height}.svg
GET /api/v1/circles/progress/{background}/{colors}/{percent}.svg
GET /api/v1/circles/progress/{background}/{colors}/{percent}/{width}x{height}.svg
GET /api/v1/circles/running/{color}.svg
GET /api/v1/circles/running/{color}/{width}x{height}.svg
GET /api/v1/circles/gradient/22aa88-ffcc33-ee4444.svg
GET /api/v1/circles/progress/f0f4f3/22aa88-ffcc33-ee4444/65/200x200.svg
GET /api/v1/circles/running/22aa88.svg
colors is a hyphen-separated list of 2–4 colors; running uses one. Colors accept 3/6-digit RGB hex without #, exact eColor names, standard named colors or transparent, case-insensitively. No numeric enum indices or substring guesses. Dimensions default to 200 × 200, or accept 16–4096 pixels each. SVG only; all parameters are in the path, without a query string.
The gradient fills the rectangular viewport, matching the old angular background (starts at the bottom, clockwise). The progress disc stays circular: integer percent 0–100 draws that many square marks clockwise from the top. Colors interpolate over the full 100-percent scale. Zero has no marks; 100 has all 100. The running semicircle rotates once per five seconds using native CSS and stops for reduced-motion preferences. Supply alternative text when embedding images.
These images contain complete, fixed presentation data, so all three may be cached on private disk for 24 hours (maximum 512 variants/32 MiB). Cache keys include normalized colors, type, percentage, dimensions and renderer version; files are atomically written outside wwwroot. Repeated requests reuse disk files. Cache I/O failures fall back to rendering. Responses use image/svg+xml, a public 600-second browser cache and ETag/If-None-Match with 304. This is separate from document graphs, which still cache only completed documents.
Errors: 400 for invalid color lists, unknown colors, noninteger/out-of-range percentage or size (not silently clamped); validated rendering errors include code: invalid-circle-parameters. Malformed integers use standard validation ProblemDetails. 404 for unsupported routes/formats such as PNG. 429 when 16 simultaneous circle requests are already active; retry with backoff. New operations, not legacy URL aliases. Generated clients and downloadable packages are synchronized in version 0.4.2.
The public icon catalogue, presentation and image GET operations allow cross-origin browser reads without credentials. Use credentials: 'omit' for fetch and crossorigin="anonymous" for images. These routes do not perform business lookups; manager and session routes retain their configured origin restrictions and authorization.
API-computed IconKid
For location responses using house, the API fills IconKid.Text with the location's LocationId. g/house displays this text centered in black inside the house, fitting it to the available space. The icon test page accepts a text value for previewing; a bare house without location context has no number.
Presentation responses use iconKid (C#: IconKid), replacing icon. Related fields are bankIconKid and unitIconKid. Use these strings unchanged, URL-encoded, in /api/v1/icon/g/{kid}.svg. The API constructs the KID: an icon alone is its exact eIcon.ToString() name; additional text, count, colour or icons use canonical Kid.ToString(). Bank/location/unit numbers are already in Text. Calendar uses today's day of month (1–31) in Europe/Copenhagen, resolved before the URL is created. Refreshing metadata after midnight gives a new filename; image caching is unchanged.
GetIconPresentation — GET /api/v1/icon/presentation?iconKid=calendar returns {"iconKid":"..."}. Public presentation only: no login, database lookup, business grant or mutation. Optional text (up to 128 characters without controls), signed Int64 count and RGB color (0–1073741823) replace those fields; other fields survive. Calendar defaults to today's day; pass useCalendarText=true with text to show the supplied text instead, for example ?iconKid=calendar&text=2&useCalendarText=true. Invalid parameters return 400; on network/503 failure keep the previous image and retry later. Metadata is no-store; do not change an existing image's cache rules.
Clients select permitted settings from availableIcons and still submit the enum name in icon-edit requests (icon or the Icon setting). Service responses additionally provide iconName for the selected setting. GetActiveLocationCount returns both count and the complete iconKid; do not assemble the badge in the client. An IconKid never authorizes access. See the changelog; generated clients and downloadable packages are synchronized in version 0.4.2.
GetIconAssetCatalog: GET /api/v1/icon/catalog/g returns a sorted JSON array of canonical eIcon names with a file directly in g (use line for that set). For a picker, intersect these names with availableIcons from the business response; missing assets should not be shown. No login or permissions are required to read the catalog, and it grants no write access. Rendering fallback from other sets is not included. Unknown sets return 404; retry 429/503 with backoff. The catalog is cached for ten minutes and reflects the deployed assets.
GetIconFromSet, GetIconImageFromSet and GetIconImageWithBackgroundFromSet render packaged local assets. No login, Tab, operation permission, database lookup or external icon server is required. Other KID fields do not select tenant data or grant permissions.
GET /api/v1/icon/{iconSet}/{kid}.{format}
GET /api/v1/icon/{iconSet}/{kid}/{size}.{format}
GET /api/v1/icon/{iconSet}/{kid}/{backColor}/{size}.{format}
GET /api/v1/icon/line/413132x7qE20i11Bi336699Ic.svg
GET /api/v1/icon/g/413132xE20i11Bi336699Ic/128.png
GET /api/v1/icon/line/house/white/128.jpg
kid is a canonical Kombine.Flex.Kid.ToString() value. The API reads Kid.Icons, Kid.Count (Int64), Kid.Color and Kid.Text. For example, Kid.Icons = [house, check], Count = 7, Color = 0x336699, Text = "A12" produces 413132x7qE20i11Bi336699Ic. If canonical KID parsing fails, an exact case-insensitive eIcon name is accepted with count zero, black and empty text; house and HOUSE work. Numeric enum IDs, indices and substring matches are not name fallbacks. Unknown names, malformed/noncanonical KIDs and undefined icons return 400. A valid KID without an explicit icon uses eIcon.none.
The separate count, color, text and sub segments and all routes without iconSet are removed. Choose line or g. Kid.Color uses the low 30 bits as opaque RGB: 0 is black, 0xFFFFFF is white, and the high byte is ignored to preserve Flex eColor semantics (ARGB values produce the same RGB). Kid.Text is case-sensitive UTF-8 text, up to 128 characters without controls, used only by assets with a text box. The canonical KID may contain up to 2048 characters after text encoding; URL-encode it as one path segment. Count = 0 hides the badge. Nonzero counts display their full absolute value: positive counts use a white capsule with black digits; negative counts use a red capsule with white digits. Capsules have circular ends and a straight middle. The badge widens for extra digits without stretching its end caps or changing its height/font size; very long labels widen the SVG canvas. The SVG title also retains the full count. The first entry, Kid.Icons[0] (also exposed as Kid.Icon), selects the main icon; Kid.Icons[1] selects the under-icon. A missing second entry or eIcon.none omits the under-icon. An empty list uses eIcon.none as the main icon. Further entries are ignored for rendering, but all entries must be defined eIcon values. Other parameters remain limited to 128 characters. No query parameters are used.
Formats: svg, png, jpg/jpeg, gif, bmp, tif/tiff, webp, ppm, tga, ico. Size is clamped to 16–4096 pixels (ICO at most 256). SVG retains its authored viewport; size/background affect raster images. Omit the background segment for transparent raster output. Unknown formats return SVG with image/svg+xml, matching the existing endpoint. Raster notification labels use the bundled Noto Sans Bold font.
On the first request the image is rendered and saved to local disk; the same variant is then streamed from disk, including after a restart if that disk is retained. Old cache entries can be evicted; replacement hosts/deployments may have an empty cache. Responses use a ten-minute public browser cache and support ETag/Last-Modified conditional requests with 304. Handle 400 for invalid/oversized parameters, 404 for missing local assets, 429 for concurrency limits and 503 for unavailable rendering/storage; retry transient errors with backoff. No database fallback or public cache-clear route is provided.
Icon sets:g preserves the original multicolor SVGs; line uses its palette/text annotations. Main and under-icon each try the selected set first, then the other packaged sets in ordinal alphabetical order for the same identity. They may come from different sets. Unknown sets or assets absent from every local set return 404. Catalogs list only direct membership, and disk-cache identity includes the selected set. For example, /api/v1/icon/g/jaa_ckey.svg uses the line asset because g does not contain jaa_ckey.
Migration: add the main icon and optional under-icon to Kid.Icons in that order, set Count, Color and Text on the Kid, URL-encode ToString(), select the set and remove the count/color/text/sub segments. An exact eIcon name still works for black icons without text or badges. Old paths are not compatibility aliases; rebuild stored URLs and follow the public changelog. Generated clients and downloadable packages are synchronized in version 0.4.2.
Daily cleanup removes rendered variants unused for 100 days by default. The API tracks use independently of filesystem access times. Capacity limits can evict variants sooner; a later request regenerates them from the original bundled assets.
Services — fixed service identities
GetServices: GET /api/v1/services lists the concrete service values of eUserId, including those without saved settings. Range-end markers are excluded. Each item has a canonical kid, enum identity (ToString), name and iconKid. Only Name and Icon are selected from this site's A{TenantId:D4}.Log7, BankId 0. The finite catalog is returned in one response; nextCursor is null. Optional filter is a literal case-insensitive match on identity or name (maximum 128 characters); sort=identity|name, direction=asc|desc. Identity sorting uses its numeric enum value.
GetService: GET /api/v1/services/{serviceKid} returns service, hasApiKeyHash, apiKeyHash, canEdit, profileRevision and availableIcons. A service KID uses the existing Manager type, this site's tenant, bank zero and a concrete service ID. Do not construct a human manager KID or infer permissions from its type.
Permissions and editing
All calls require an active manager session, Services1 (60), independent PermissionService2.Read and a whole-tenant KID grant. Editing additionally requires Service Write. Readers receive a null apiKeyHash; only editors receive the stored hash. Treat it as sensitive and do not log it. Hashes never appear in directory responses.
Service endpoint authorization
Service accounts do not use a permission matrix, assigned KID scopes or tabs. Each endpoint explicitly decides which authenticated eUserId values it accepts: synchronization requires eUserId.ServiceSync; authenticated status accepts all supported service identities. Account state, key validity and the configured tenant remain enforced. Stored legacy access settings are preserved but are neither returned nor editable. GetService no longer returns access. Service permission, role, tab and KID assignment routes have been removed; stop calling them. Manager authorization for listing and editing services is unchanged. See the changelog. Client regeneration is deferred to beta.
SetServiceProfileField: POST /api/v1/services/{serviceKid}/profile/{field} saves exactly one field: Name or Icon. Name allows up to 200 non-control characters. Icon must be a selectable name from availableIcons (all known positive eIcon values); a safe legacy current icon is prepended for display only. ApiKeyHash is read-only: attempting to write or clear it returns HTTP 400 invalid-service-profile, including when the value is empty. Use GenerateServiceApiKey below to replace the API key; never submit a plaintext key or a manually computed hash. Existing stored hashes remain unchanged until a new key is generated. See the Changelog for migration details.
Each write rechecks the actor's current account, credential stamp, tab, rights and scope inside a serializable transaction. One setting is appended to bank-zero Log7 history; unchanged values add no history. Wait for the complete 200 response before updating the UI and retain the returned revision. No automatic write retries. Responses are no-store; requests have a 12-second deadline and writes allow a maximum 4096-byte body.
const headers = { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' };
const listResponse = await fetch(`${api}/api/v1/services?sort=name&direction=asc`, { headers });
if (!listResponse.ok) throw new Error(`GetServices: ${listResponse.status}`);
const { items } = await listResponse.json();
const serviceKid = items[0]?.kid;
if (!serviceKid) throw new Error('No services');
const detailResponse = await fetch(`${api}/api/v1/services/${serviceKid}`, { headers });
if (!detailResponse.ok) throw new Error(`GetService: ${detailResponse.status}`);
const detail = await detailResponse.json();
if (!detail.canEdit) throw new Error('Service Write is required');
const saved = await fetch(`${api}/api/v1/services/${serviceKid}/profile/Name`, {
method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ value: 'Scheduled integration', expectedRevision: detail.profileRevision })
});
if (!saved.ok) throw new Error(`SetServiceProfileField: ${saved.status}; reload before retry`);
const confirmed = await saved.json();
Errors: 400 invalid-filter/invalid-sort/invalid-service-kid/invalid-service-profile — correct the request. 401 — log in again. 403 missing-services-tab/missing-services-read/missing-services-write/missing-tenant-access — request the missing access. 409 service-profile-conflict — reread and review changes. 503 services-unavailable — reread before a manual retry; a lost acknowledgement can have an uncertain outcome. Do not display a failed save as successful.
Generate a new API key
GenerateServiceApiKey: POST /api/v1/services/{serviceKid}/api-key accepts {"expectedRevision":"<profileRevision from GetService>"}. It requires the same Service Read/Write, Services1 and whole-tenant access as profile edits, including fresh authorization inside the transaction.
The API generates kt_ followed by 64 cryptographically random ASCII letters and digits, always including both uppercase and lowercase letters. Keys are case-sensitive. It stores only the hash in eSetting.ApiKeyHash, using exactly the existing manager password function (HubManager.SHA512Salt compatible). This replaces the previous hash. The successful response contains apiKey and details, including the committed hash and new revision. The plaintext key is returned only by this call and cannot be recovered through GetService. Show/copy it only after a confirmed response; do not log the response or put the key in browser storage, URLs or analytics. The portal clears its displayed key on navigation or replacement.
Service key hashes are stored in eSetting.ApiKeyHash, the same Log7 setting as manager passwords. eSetting.ApiKeyHash is no longer read or written. Before switching an installation to this version, move any existing service hashes to Password through the Log7 history mechanism, without overwriting an existing Password, or generate replacement keys in Portal. Existing plaintext keys continue to work if their hashes are moved unchanged. There is no automatic migration or fallback. The JSON fields apiKeyHash and hasApiKeyHash keep their names and describe Password; manual credential editing remains prohibited.
Uses the same 400/401/403/409/503 errors, no-store, 12-second deadline and 4096-byte request limit as profile editing. After a timeout or lost response, reread before manually generating again: the previous request may have committed. Never retry automatically. This does not enable service authentication. Generated clients and downloadable packages are synchronized in version 0.4.2.
In Swagger, choose Downloads v1 under Select a definition for resident CSV, account CSV/Excel, settlement ZIP and document CSV/XLS exports. Use the same manager bearer token and permissions. The complete integration OpenAPI document still includes these operations for client tools.
Managers may share an email address if their passwords differ. If several accounts match both email and password, login keeps the active, non-deleted manager with the newest eSetting.Alive krumb MS2000 and atomically clears Password on the other matching managers. Activity comes from the krumb timestamp, never its Text value. Missing or invalid timestamps rank behind valid activity; equal timestamps, including all unknown, are resolved by the lowest UserId. Credentials and activity are re-read under transaction locks before cleanup. Accounts with a different password remain unchanged; permissions are never merged. Without an active matching account, no cleanup occurs. Read GetCurrentManager after login to identify the selected account.
No token is issued until duplicate cleanup commits. Unavailable storage, failed cleanup or more than 100 matching rows return HTTP 503. Do not automatically retry an uncertain result. Sessions belonging to accounts whose passwords were cleared become invalid; other API instances may retain their existing account snapshot for up to 60 seconds. Request and token response fields are unchanged.
Failed login attempts may be recorded as internal JSON diagnostics. Client status codes and responses are unchanged; internal reasons such as duplicate email/password pairs are not disclosed by login. Operators can correlate the request trace ID with API logs. Never include passwords or tokens in error reports.
Login and manager settings use the site's own A{TenantId:D4}.Log7, BankId 0. D4 pads the tenant ID to at least four digits: Team 166 uses A0166.Log7. The server's PortalSite:TenantId selects the tenant; there is no fallback to another tenant's manager database.
A manager must have Enabled = 1. An absent Deleted row (or SQL NULL) defaults to 0: not deleted. Present invalid Deleted values and positive deletion timestamps still block login.
1. From API address to your first login
The API base address for this tenant site is https://api.team.kombine.technology. Use the API address, not the portal address.
Examples automatically use the address of the API site serving this guide. Beta shows the beta address. Without JavaScript, the Team production address is shown; check the address before use. You cannot switch tenants by adding a field, query parameter, or header. The server determines the site and permissions.
Request
Purpose
Authentication
GET /api/v1/public/statistics/purchases
Purchase count for the last hour
None
GET /api/v1/public/statistics/active-users
Active-user count for the site's tenant
None
GET /api/v1/status
Check whether the API responds. Does not check MySQL.
None
POST /api/v1/session/login
Exchange a manager email and password for a temporary access token.
Email and password in JSON
GET /api/v1/session/me
Retrieve your own profile and current permissions together.
Access token
Try it without writing a program
Open Swagger and select Portal integrations v1. Swagger is a web page for reading about and trying API requests.
Expand GetPortalStatus, select Try it out, then Execute. HTTP 200 means the request succeeded.
Expand LoginManager. Replace the example email and password with your manager’s credentials and select Execute. All example credentials are fictitious and cannot log in.
Copy only the accessToken value from the response, without quotation marks. Click Authorize, paste it under ManagerBearer, and authorize. Swagger adds the Bearer prefix.
Run GetCurrentManager. Its response provides the information for your portal’s profile and access cards.
A manager must be enabled and not deleted. Missing Tabs or bank access do not prevent login itself; explain the missing access in your portal.
The HTTP requests
POST https://api.team.kombine.technology/api/v1/session/login
Content-Type: application/json
Accept: application/json
{"email":"manager@example.test","password":"<your password>"}
Send the original password over HTTPS. The API verifies it; do not encode or hash it in the client.
GET https://api.team.kombine.technology/api/v1/session/me
Authorization: Bearer <your access token>
Accept: application/json
The token lasts ten days (864,000 seconds) from login or renewal. Treat it as a secret string: it is not a JWT to decode. Read expiresIn instead of hard-coding the duration. Before expiry, replace it through RenewManagerSession after user activity; ordinary API calls do not extend it. An expired token requires login. No separate refresh token or single-token revocation endpoint is provided. On logout, your client discards its token; an existing copy retains its original expiry, subject to account/password revocation.
GetCurrentManager (GET /api/v1/session/me) includes optional gravatarUrl for the authenticated manager. Prefer this picture in the signed-in account menu; use iconKid when null or the image fails, including HTTP 404. The URL uses the normalized email's SHA-256 hash, 96 px, G rating and d=404; the API does not contact Gravatar. Direct browser requests disclose the email hash and client IP to Gravatar. This display hint grants no permissions and needs no manager-directory access. Unreleased.
Wallboard1 layout editor — unreleased, available on alfa
Existing recognized layouts in the previous JSON format are converted in memory for reads and migrated to the compact format on the next successful save. GET does not modify stored data. Unknown or malformed saved fields are retained and prevent replacement.
Both collection responses include storageUsedCharacters and storageLimitCharacters. These count the exact committed Log7 JSON text and its shared 4092-character limit across the physical wallboards, not the size of the HTTP response or unsaved drafts. Whitespace and JSON escapes count. Remaining space is max(0, limit - used). Widget type 0 (None) is an empty occupied rectangle with an empty or style-only KID; it renders no content and performs no widget requests. The editor creates this type by default.
The physical wallboards collection and the separate portal layout each have their own 4092-character budget. storageUsedCharacters/storageLimitCharacters count physical layouts; portalStorageUsedCharacters/portalStorageLimitCharacters count the portal layout.
Each page supports up to 48 widgets, subject to its grid and the applicable 4092-character storage budget.
GetMyManagerWallboards — GET /api/v1/session/me/wallboards returns the physical wallboards array, a separate portalWallboard object and an opaque revision covering both settings. SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards accepts both fields with that revision and saves them atomically, including page transfers between them. Both require an active manager and eTab.Wallboard1; screen and service sessions cannot edit. Credentials, API-key revocation, tab access, widget resource grants and revision are checked under the bank-zero Log7 lock. Only the manager-owned eSetting.WallBoards and eSetting.PortalWallboard change; device approvals and grants are unchanged. An empty wallboards array removes physical layouts only.
portalWallboard is always returned, including an empty in-memory default when the setting is absent; GET never writes data. Show it first and do not offer deletion. It uses the compact layout model, but its i is schema metadata, never an approved screen ID. Preserve the exact returned i on PUT; the default is ["PortalWallboard"]. Omitting portalWallboard preserves the setting for older clients; explicit null and arrays are invalid. Sending it requires the latest combined revision. Known older formats and geometry remain readable; invalid stored data blocks replacement. This editor integration does not change Home/Overview.
The editor adds screens through QR scanning only. It cannot create or copy a display or change its ID. SaveMyManagerWallboards now requires every ID in i to exist in the current manager's stored collection; new or renamed IDs return HTTP 400 wallboard-scan-required. Scan first, then reread the collection and revision. Existing stored displays remain editable. Text and number fields save when they lose focus, never on each keystroke. Other completed edits save immediately. Writes are serialized; focused drafts are excluded from earlier queued saves, and later edits use the returned revision. Navigation waits for every pending change without a discard confirmation. If saving fails, the draft remains in the editor. Errors/conflicts stop automatic saves and retain the draft; uncertain writes are never retried automatically. Visible screens keep a revision-aware read open; a committed editor save wakes it immediately on the same API instance. Editing another page does not restart the current page's duration.
Enums 2.0.160 layout: i is a nonempty ordered array of display IDs, n is the name, numeric a is the positive finite aspect ratio (width divided by height), defaulting to 16:9, and s contains ordered pages. A page has n/d/s; a widget has numeric t, KID k, and r: [x,y,width,height]. Origins are zero-based on the 60 × 60 grid; rectangles cannot overlap or cross its boundary. Each display ID must already be scanned for this manager and appear only once in the complete collection. A screen session sees only its own ID; manager sessions see the full array. Page duration is 1–86400 seconds. Pages/widgets have no stored IDs. Stored older formats are read and converted on save without rescaling; the shared storage limit is 4092 characters.
Direct video URL. Widget 56 plays an HTTPS video file or HLS playlist (.m3u8) directly in the browser. Store the address in Kid.Text and set Kid.Crc to 1 for sound or 0 for muted playback (default). An empty address is unconfigured. Anonymous wallboards accept only public links without access tokens.
Plex (52) is available on protected personal wallboards for the configured Kombine Home profile. Public wallboards cannot expose Plex. Legacy invalid references are retained unchanged and can only be repaired under the existing revision and authorization rules.
The saved a controls the editor canvas and its previews. The actual player fits its current viewport in both dimensions, including after resizing or rotation; it does not letterbox to a. Widget coordinates remain on the unchanged 60 × 60 grid, with the configured edge spacing and gaps. An editor-only aspect change does not restart the playing page. Older stored orientation pairs still use the existing portrait/landscape lookup to select their content.
Enums 2.0.160 requires both dimensions of new or changed widgets to be at least 3 cells (maximum 60, within the grid). An omitted r defaults to [0,0,3,3] on PUT. Previously stored smaller widgets and omitted rectangles retain their original dimensions on GET; reads never resize or write data. A PUT may retain smaller widgets unchanged: each submitted t/k/r must match a distinct widget in the freshly authorized, revision-locked stored collection. This permits edits elsewhere, page reordering and deletion without resizing old widgets. New, copied or changed smaller widgets return HTTP 400 invalid-wallboards without writing. New editor widgets start at up to 20 × 20, reducing to at least 3 × 3 when space is limited. The selected editor grid affects snapping only.
Existing stored cell coordinates and sizes are kept unchanged when read or saved. A width of 12 occupies one fifth of the new grid. Layouts have no stored grid-version marker, so clients must not automatically infer or repeat a rescale. Review older layouts and adjust their positions and sizes explicitly with the latest revision if the previous relative appearance is required.
Unreleased background extension: optional c contains two ordered palettes, light then dark, each with zero to three signed 32-bit color values. No colors use the default background; one gives a solid background, two a linear gradient and three a circular gradient. The low 24 bits are RGB; the high byte records order, not opacity. Older stored single palettes are converted in memory to identical light and dark palettes without rewriting the saved layout. Empty palettes may be omitted from stored JSON; responses may include them. Null and palettes with more than three colors are rejected.
On PUT, omitting c preserves saved palettes when the selected displays match; combining differing palettes requires an explicit value. Send "c":[[],[]] to clear both. Keep the latest revision and existing screen IDs; authorization and revision checks remain.
The current video type is eWidgetType.YouTube (39). Existing stored Video (26) widgets are returned as YouTube (39), for both physical layouts and portalWallboard, without database writes or revision changes. GET and the display endpoint, including ?after=REVISION waits, return the canonical type. PUT accepts legacy t:26 as an input alias, validates it as YouTube and writes t:39 on the next successful authorized, revision-checked save. The KID, rectangle, ordering and other content remain unchanged; unchanged older small widgets retain their existing protection. Video (26) is no longer separately selectable. eSetting.PortalWallboardPublic (3551) remains inactive; these operations do not read or write the public-wallboard setting.
Supported types: 1 ActiveUsers, 2 Purchases, 3 RunningMachines, 4 Reservations, 5 LiveMachines, 6 WashDoc, 7 PurchaseMap, 8 RevenueHeatmap, 9 RecentPhotos, 10 AutoOutOfOrder, 21 Icon, 22 Logo, 23 Weather, 24 Clock, 25 Text, 29 ReservationCalendar, 36 LocationMap, 39 YouTube, 40 Vimeo, 41 Wistia, 42 LiveLocation (Location status), 43 LogoMark, 44 LogoWordmark, 45 Mux, 46 LocationInfo, 47 ReservedMachines, 48 ActiveManagers and 52 Plex. Team additionally supports 49 PortalWebLoad, 50 PortalApiLoad and 51 EquipmentApiLoad. Team additionally supports 37 DatabaseLoadHistory; all configured tenants support 38 DatabaseBankStorage, through the protected APIs described below. All other types, including reserved 11–20 and unimplemented 27–28 and 30–35, are rejected. Types 1–10 use the existing public, tenant-bound data. Widget k may be empty, or a canonical KID whose Style is 1 (light) or 2 (dark). For a widget without a target, 1Is and 2Is are canonical style-only KIDs. Other style values and non-canonical KIDs are rejected. LiveMachines can target a bank, location or unit; WashDoc can target a unit or document. Their full KID may include the style; the API removes style before validating and authorizing the canonical resource identity against the current tenant and resource grants. Icon accepts at most one defined icon and optional style, as described below. Text accepts only its text content and optional style, as described below. YouTube, Vimeo, Wistia, Mux and Plex store canonical media references in Kid.Text with optional sound and style, as described below. ReservationCalendar, LiveLocation and LocationInfo accept a canonical location KID with optional style, as described below. Other types accept only an empty or style-only KID, unless otherwise described. Style is presentation, not an authorization grant. All widgets follow the current wallboard light/dark theme; legacy KID styles are preserved but do not select the player theme. Widgets adapt to their container dimensions and aspect ratio.
PUT /api/v1/session/me/wallboards
Authorization: Bearer <manager-session>
Content-Type: application/json
{"revision":"<revision from GET>","portalWallboard":{"i":["PortalWallboard"],"n":"","a":1.7777778,"s":[]},"wallboards":[{"i":["Lobby"],"n":"Lobby","a":1.7777778,"c":[[19803451,83886079],[19803451,83886079]],"s":[{"n":"Overview","d":30,"s":[{"t":1,"k":"2Is","r":[0,0,6,6]}]}]}]}
Success: 200 with the saved physical array, portal singleton, independent storage counts and new combined revision. Errors: 400 invalid-wallboards / invalid-wallboard-widget, 401 stale/inactive login, 403 missing-wallboard-tab, 409 wallboards-conflict, wallboards-limit or invalid-stored-wallboards, 503 unavailable/uncertain storage. On conflict, explicitly reload and reconcile; on uncertain storage, read back before deciding whether to save again. No automatic write retries. Unknown stored fields and malformed legacy layouts are preserved and block replacement rather than being silently erased.
GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId}?portrait=false returns {"layout":...,"revision":...,"dateFormat":"dd-MM-yyyy HH:mm"}; a missing layout returns layout:null. The other orientation is the fallback. Managers need Wallboard1; approved read-only screens can read only their exact display ID. Current credentials, tab, scoped-widget grants and device approval are checked before returning.
For immediate updates, send the last 64-hex revision as optional after. If unchanged, the request waits up to eight seconds. A committed save on the same API instance wakes it immediately, including for screens on another computer. The response shape is unchanged on timeout; immediately reconnect with the returned revision. Changes from another API replica or an external writer are discovered at timeout. Only one request should be outstanding per screen; cancel when hidden or leaving. Changed content on the current page renders immediately; editing another page preserves the current page's duration.
GET /api/v1/session/me/wallboards/display/Lobby?portrait=false&after={lastRevision}
Authorization: Bearer {managerOrScreenToken}
Errors: 400 invalid-wallboard-revision, 401/403 revoked or insufficient access, 429 wallboard-watch-limit (back off; at most 64 waits per manager), 503 unavailable. Stop displaying protected content on access failure; retry failed reads with increasing delay. Writes are never retried automatically. Client packages follow the next beta. This Portal change is released separately from the standalone Wallboard host.
Both recognized older stored schemas remain readable without writes. One-based coordinates become zero-based, Boolean orientation becomes 0/1, and page/widget IDs are omitted while preserving content and order. Existing orientation pairs remain readable in the editor and on approved screens; move any needed pages and remove the redundant layout before saving one layout per display. The API never automatically merges or drops them. QR registration appends the display without rewriting existing objects. Unknown or ambiguous fields block replacement. Page links address ordered positions instead of persistent IDs.
Clock and weather — unreleased, available on alfa
All configured tenants support eWidgetType.Clock (24) and Weather (23), each with an empty or style-only KID. Existing Wallboard1, layout ownership, revision and approved-screen checks still apply. Other unimplemented types remain unavailable.
Clock shows the device's local time above a smaller date, centered together as a block at the widget's bottom right. The date uses a localized month name independently of the owner's numeric date pattern. The time uses the shared tenant/theme numeric value color (Team: blue in light mode, yellow in dark mode); the date uses the normal theme text color. GetMyManagerWallboards and GetMyManagerWallboardDisplay include the authorized owner's validated dateFormat, for example dd-MM-yyyy HH:mm or MM/dd/yyyy hh:mm tt. Honor its 12/24-hour time preference; empty and date-only values retain the language's clock format. Render the time in hours and minutes. Use the device's clock and time zone, not the weather location's zone. Read this preference on every display response, even when the layout revision is unchanged. No layout migration or write is needed.
Weather uses the standalone Wallboard API, GetWallboardLocalWeather — GET /api/weather?displayId={screenId}. Use the exact active screen ID, not always the first ID in a multi-screen layout. The stored scan position takes precedence; without it, use the requesting browser's public IP. A bounded Photon reverse lookup supplies the saved position's optional city/locality name; unknown names remain blank, and source links are available in the widget's information disclosure. A personal Portal wallboard omits the screen ID. This is a credential-free browser request to https://alfa.wallboard.kombine.equipment on alfa or https://wallboard.kombine.equipment in production. Never send a manager bearer token or proxy the request through a server whose IP would replace the screen's IP.
GET https://alfa.wallboard.kombine.equipment/api/weather?displayId=Lobby
[{"t":23,"k":"2Is","r":[0,0,20,20]},{"t":24,"k":"","r":[20,0,20,20]}]
The weather response reports status (Available, LocationUnknown or Unavailable), Celsius temperatureCelsius, weatherCode, area, timeZone and observedAtUtc. Missing readings remain null, never zero. IP location is approximate. The existing needsPublicIp fallback applies when the connection address is private: discover the browser's public address and repeat with its validated publicIp hint. It is used only for weather, never authorization. No GPS prompt, coordinates, IP or provider credentials are returned. Cache and rate limits remain owned by the standalone API; refresh visible weather every ten minutes, retry unavailable data after one minute, and cancel work when hidden or removed. The clock runs independently of weather availability.
Optional positionSource is screen or ip on success; isDay is true, false or null and controls the day/night icon. A saved position is the scan location, not live GPS; its area may be empty. Invalid screen IDs return HTTP 400; HTTP 429 requires respecting Retry-After. These public weather reads neither approve a screen nor grant access to a Portal layout.
Icon — unreleased, available on alfa
eWidgetType.Icon (21) displays Kid.Icon, the first entry in Kid.Icons. The canonical widget KID may contain at most one defined eIcon and optional Style 1 (light) or 2 (dark). An empty KID, style-only KID or eIcon.none means no icon is selected and renders no icon. Resource targets, additional icons, Text, Count, Color and other fields are not accepted in this widget's saved KID.
{"t":21,"k":"E20i2Is","r":[0,0,20,20]}
This example shows eIcon.house (3616 / hexadecimal E20) in dark mode. Generate the KID with new Kid { Icon = eIcon.house, Style = 2 }.ToString(); a light icon may omit Style. The editor uses the standard searchable selector, intersecting the installed eIcon names with the existing line and g asset catalogues. Changing the icon preserves its theme and uses the normal serial, revision-checked save.
Rendering reuses GetIconPresentation — GET /api/v1/icon/presentation and GetIconFromSet — GET /api/v1/icon/line/{kid}.svg on the trusted tenant API. No login or business lookup is needed for these public presentation operations. The requested black/light-theme or white/dark-theme image color is separate from the saved KID. The API retains its normal asset fallback, including original multicolor g artwork. Icons are centered and contained without cropping or distortion inside the existing themed widget container.
The browser omits credentials when requesting presentation metadata, bounds the request to 15 seconds and cancels it when the widget is removed. A failed metadata/image request shows the existing unavailable state; it never substitutes an unrelated icon or writes layout data. Saving still requires the usual manager permissions, display approval, revision and storage checks. Other unsupported types remain disabled. Client regeneration follows the next beta release.
Tenant logo widget — unreleased, available on alfa
eWidgetType.Logo (22) displays the current API tenant's full logo. Its KID is empty or contains only Style 1 (light) or 2 (dark); the optional style is retained as metadata; the wallboard supplies the actual theme. Resource identities, text and other KID fields are rejected. The widget cannot select another tenant, upload an asset or choose an arbitrary logo URL.
The existing public GetPublicWidgetPresentation — GET /api/v1/public/widgets response now includes brandName, brandLogoUrl and brandDarkLogoUrl, resolved by the shared tenant branding profile. This is additive and requires no login or database read. Relative local asset paths are made absolute using the configured HTTPS Portal Web origin; a missing or unsafe origin produces null for those paths, never an embedding/request-host fallback. Existing absolute HTTPS logo URLs and tenant overrides remain unchanged.
{"t":22,"k":"2Is","r":[0,0,20,20]}
The official renderer chooses the light/dark logo, centers it and preserves its proportions without cropping. The existing container supplies the background and corners. Only the exact standard black Kombine logo uses the same white-on-dark transformation as the portal sidebar; other tenant logos retain their colors. The public presentation request sends no credentials; the image uses normal browser image loading with no referrer and never receives a Portal bearer token. Initialization is bounded and cancelled when the widget is removed. Missing or failed logos show the existing unavailable state, without another tenant's logo. Layout saves retain existing authorization, display binding, budgets and revision checks. Client package regeneration remains deferred to beta.
LogoMark (43) displays only the tenant logo symbol; LogoWordmark (44) displays only its wordmark. Like Logo (22), both accept only empty/style-only KIDs and have no container background. The container selects light/dark assets from GetPublicWidgetPresentation: BrandLogoMarkUrl, BrandDarkLogoMarkUrl, BrandLogoWordmarkUrl and BrandDarkLogoWordmarkUrl. Missing variants are null, without another-tenant or full-logo fallback. Approved-screen and public-wallboard rendering use the same implementation; authorized saves and revision checks are unchanged.
Text widget — unreleased, available on alfa
eWidgetType.Text (25) displays Kid.Text as plain text on every configured tenant. It makes no separate data request and does not interpret HTML, Markdown or URLs. The editor provides a standard text field, commits on blur, and displays wrapping text in the existing light/dark widget container.
Create the KID through new Kid { Text = "Hello world", Style = 2 }.ToString() (C#) / (New Kid With {.Text = "Hello world", .Style = 2}).ToString() (VB.NET). Its canonical representation contains uppercase UTF-8 byte hex followed by x, and optionally 1Is or 2Is for light/dark. Empty text is valid and shows no placeholder. The optional style is retained as metadata; the wallboard supplies the actual theme. Resource identities, other KID fields and unsupported styles are rejected for Text; KID contents never grant access.
The existing 2048-character KID limit and 4096-character budget per wallboard setting remain unchanged; hex encoding consumes two characters per UTF-8 byte, plus field/style markers. The current Kid package cannot safely round-trip control characters such as tab, CR or LF, so these are rejected rather than changed or lost. Use ordinary text with automatic visual wrapping. Malformed UTF-8 or non-canonical KIDs are also rejected. Saving uses the existing fresh authorization, display binding and revision checks; no stored layout is changed automatically.
Video sound — unreleased, available on alfa
YouTube (39), Vimeo (40), Wistia (41), Mux (45) and Plex (52) use Kid.Crc: 0 or absent means muted; 1 enables sound. Multiple widgets on the same page may have sound. This is independent of Kid.Text (media reference) and Kid.Style; selecting another video preserves both settings. Other Crc values and extra KID fields return 400 invalid-wallboard-widget. Text widgets do not accept Crc. Save through the normal authorized, revision-checked layout operation; no new permissions or stored-data migration are introduced. Plex remains unavailable on anonymous wallboards.
new Kid { Text = "M7lc1UVf-VE", Crc = 1, Style = 2 }.ToString()
// 4D376C63315556662D5645x1J2Is
{"t":39,"k":"4D376C63315556662D5645x1J2Is","r":[0,0,20,20]}
The Sound selector saves each widget separately. The two light/dark comparison previews remain muted; the full Preview and wallboard player follow the saved choice. Browser autoplay restrictions can require a click on the player; Plex and Vimeo show Play with sound when necessary, while YouTube, Wistia and Mux retain player controls. Hidden/removed players stop as before. Crc=0 is omitted in canonical KIDs; Crc=1 is encoded as 1J after Text and before Style.
YouTube video — unreleased, available on alfa
eWidgetType.YouTube (39) plays one YouTube video. Its canonical KID contains only Kid.Text with the 11-character video ID ([A-Za-z0-9_-]{11}) and optional Crc 0/1 and Style 1/2. Empty or style-only KIDs remain unconfigured and contact no video provider. Other KID fields, full URLs, HTML, playlists, resource scopes and malformed IDs are rejected with 400 invalid-wallboard-widget. The API does not fetch YouTube content or use a YouTube API key.
// Official YouTube player example: M7lc1UVf-VE
new Kid { Text = "M7lc1UVf-VE", Style = 2 }.ToString()
// 4D376C63315556662D5645x2Is
{"t":39,"k":"4D376C63315556662D5645x2Is","r":[0,0,20,20]}
The editor accepts a video ID or a recognized HTTPS YouTube link and extracts only the ID. The standard field commits on blur, preserves the widget theme and uses the existing serial save/revision checks. URL query parameters such as playlist, tracking and start time are not saved. Reads do not change stored data, video IDs, geometry or permissions.
Playback uses a fixed https://www.youtube-nocookie.com/embed/{id} frame and the official https://www.youtube.com/iframe_api script. The frame supplies the portal origin, uses strict-origin-when-cross-origin referrer policy and keeps YouTube's controls. Portal sessions, KIDs and page URLs are not appended to YouTube requests. The player needs internet access and permission to embed the selected video; removed, private, age-restricted or embedding-disabled content may not play.
The widget attempts playback with the configured sound and repeats the selected video. At most one player starts automatically per browser document, only when more than half visible. Other players retain manual controls. The complete 16:9 player is fitted and centered inside the widget, leaving the remaining space transparent. YouTube's 200 × 200 pixel minimum applies to the fitted player, so the widget needs approximately 356 × 200 pixels; smaller widgets show a localized size hint instead of clipping the player. Portrait or other non-16:9 videos, and bars embedded in the video itself, may still show black bars. These are rendered pixel dimensions, not the stored 60 × 60 grid coordinates. Hiding/removing the widget or changing wallboard page stops its player; the existing page duration still determines page changes. Browser autoplay rules can require a manual click. Light/dark Style applies to the surrounding container, not a recoloring of YouTube's interface.
Reference: YouTube IFrame Player API and embedded-player requirements. Custom CSP deployments must allow the official script and frame hosts. Existing manager/display approval, revision and storage checks remain in force; other unsupported types remain disabled. Client packages follow the next beta release.
LocationInfo — unreleased, available on alfa
eWidgetType.LocationInfo (46) currently displays only the selected location's stored name. Save a canonical same-tenant location KID in k, with optional light/dark Style. Empty/style-only is unconfigured. Other resource kinds and metadata are rejected. The standard field commits on blur; names render as plain text at the top left (NW), sized to the widget, using its theme. Geometry and the authorized revision-checked save remain unchanged.
GetMyWallboardLocationInfo and GetWallboardDisplayLocationInfo require active manager credentials, Wallboard1, Location Read and a matching tenant/bank/location grant. Screen sessions can only call their exact display route, whose selected orientation must contain type 46 with the same location (saved Style is ignored for matching). The API rechecks current authority, saved layout, location retention and device approval after reading. Names use the existing Log24 location cache for up to 60 seconds. No units, residents, coordinates or other location metadata are returned. The widget is unavailable on the anonymous public wallboard.
GET /api/v1/session/me/wallboards/location-info?locationKid=A6Q1Eo7D0b4l
GET /api/v1/session/me/wallboards/display/Lobby/location-info?portrait=false&locationKid=A6Q1Eo7D0b4l
Authorization: Bearer {manager-or-approved-screen-token}
{"locationKid":"A6Q1Eo7D0b4l","name":"Laundry"}
400: invalid/foreign KID; 401: invalid/revoked session; 403: missing permission or mismatched saved widget; 404: missing/retention-hidden location; 409: invalid stored layout; 503: data unavailable. Poll no more than once a minute while visible, cancel when hidden/removed, and clear names after denial or failed reads. Do not treat unavailable data as a location name. Client package generation follows the next beta release.
Mux video — unreleased, available on alfa
Enums 2.0.154 adds eWidgetType.Mux (45). Store only a public playback ID in Kid.Text, with optional Crc 0/1 and Style 0/1/2. Portal accepts 16–128 case-sensitive ASCII letters/digits. Empty/style-only is unconfigured. URLs, playback tokens, resource scopes and other KID metadata are rejected.
LogoMark (43) displays only the tenant logo symbol; LogoWordmark (44) displays only its wordmark. Like Logo (22), both accept only empty/style-only KIDs and have no container background. The container selects light/dark assets from GetPublicWidgetPresentation: BrandLogoMarkUrl, BrandDarkLogoMarkUrl, BrandLogoWordmarkUrl and BrandDarkLogoWordmarkUrl. Missing variants are null, without another-tenant or full-logo fallback. Approved-screen and public-wallboard rendering use the same implementation; authorized saves and revision checks are unchanged.
The standard editor extracts the ID from HTTPS player.mux.com/{id} or stream.mux.com/{id}.m3u8 links on blur. Signed links are unsupported. Kombinetech.com's video uses Qde1epxkBdUHyL8KjPOffik4AWNN6PcrLjt8bhdIzNA. The official Mux Player fills the widget with centered proportional cover, autoplay with the configured sound and looping, with controls available when sound is enabled. Browser autoplay restrictions still apply. Loading begins only when more than half the widget is visible and its dimensions are positive; hiding/removing it unloads playback, including during asynchronous player loading. Resizing does not restart playback. Layout geometry, page timing, serial saves, revisions and authorization are unchanged.
Mux is allowed on the public wallboard through the existing whole-tenant-authorized save. The playback ID is public; protected data stays protected. Tracking/cookies are disabled. Custom CSP must allow the pinned official player from cdn.jsdelivr.net and Mux streaming/image hosts, including HLS blob media/workers; see Mux Player configuration and Mux CSP guidance. Existing YouTube, Vimeo and Wistia behavior is unchanged.
Vimeo and Wistia videos — unreleased, available on alfa
eWidgetType.Vimeo (40) stores a positive decimal video ID of 1–20 digits without a leading zero in Kid.Text. For an unlisted video, append /{hash}, where the privacy hash is exactly 10 lowercase hexadecimal characters, for example 76979871/8272103f6e. eWidgetType.Wistia (41) stores a media ID of exactly 10 lowercase ASCII letters or digits, for example g5pnf59ala. These are the Portal's bounded canonical reference formats.
new Kid { Text = "76979871/8272103f6e", Style = 2 }.ToString() // Vimeo
new Kid { Text = "g5pnf59ala", Style = 1 }.ToString() // Wistia
Only Kid.Text and optional Crc 0/1 and Style 0/1/2 are allowed. Empty/style-only KIDs are unconfigured. Full URLs, HTML, resource scopes, other KID fields, uppercase references and malformed IDs are rejected with 400 invalid-wallboard-widget. The standard editor accepts recognized provider links, extracts the reference and commits on blur; Vimeo's unlisted hash is retained. Existing authorization, display binding, storage limits, serial saves, revisions and geometry remain unchanged. Layout read/save operations do not fetch provider content or require provider credentials; the shared Vimeo list below also requires no provider credentials.
Both players fill the widget with centered, proportional cover video, cropping overflow without changing the saved geometry or KID. Wistia uses fitStrategy=cover. Vimeo's official player SDK reads the video's natural dimensions to calculate the cover size; Vimeo uses looping background playback with its controls hidden. Until those dimensions are available, the frame retains its original bounds; a blocked SDK cannot provide cover sizing. Both players attempt autoplay with the configured sound and loop only while more than half visible and with nonzero dimensions. Hidden/offscreen or removed widgets destroy their players and frames; showing them again creates a new player. Frames use strict-origin-when-cross-origin and provider do-not-track options. Custom CSP configurations must permit the official frame hosts and Vimeo's player SDK; browser autoplay restrictions still apply.
References: Vimeo embedding and Vimeo player SDK, Wistia iframe embeds. The official player hosts are player.vimeo.com and fast.wistia.net. Selected videos must permit embedding; provider privacy settings and browser autoplay rules still apply. Hiding/removing the widget or changing page stops playback, while the wallboard's page duration remains authoritative. The existing YouTube (39) implementation and legacy type-26 read conversion are unchanged.
Vimeo and Wistia may also be saved in the tenant's public wallboard through the same whole-tenant authorization and revision checks as YouTube. Published provider references, including an unlisted Vimeo privacy hash, are visible in the anonymous layout response. This grants no anonymous access to protected widget data or APIs.
Plex videos and playlists
The connection requires the pinned Kombine Plex Home profile and its PIN for searches, playlists and playback. The PIN is kept in encrypted server configuration. A profile or PIN failure never falls back to the server owner’s media access; changing profiles requires a new playback ticket.
Plex (52), from Enums 2.0.160, stores a canonical machine identifier, v (video) or p (video playlist), and numeric item ID in Kid.Text. Optional Crc 0/1 and Style 0/1/2 is preserved. Empty KIDs are unconfigured. URLs, credentials and resource-scoped KIDs are rejected. Only authenticated active managers with Wallboard1 access and their approved screens may use the explicitly configured connection. An operator may explicitly share one connection across tenants and Wallboards managers; tickets and saved layouts remain tenant-bound. Anonymous/public wallboards cannot contain Plex.
Search returns at most 30 items with reference, title and kind (video or playlist). Query may be empty or up to 120 characters. Queue returns reference, title and current count. Start uses a zero-based index (0 for a single video) and returns an opaque ticket. Screens cannot search and must supply their exact approved displayId and portrait orientation for queue/start; the reference must exist in that saved layout. Stream and stop use the ticket with the same manager/screen bearer session. Relative HLS entries are further opaque tickets under the stream route. Never treat a ticket as an independent bearer credential.
GET /api/v1/session/me/wallboards/plex/search?query=example
GET /api/v1/session/me/wallboards/plex/queue?reference=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/v/123
GET /api/v1/session/me/wallboards/plex/start?reference=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/v/123&index=0
GET /api/v1/session/me/wallboards/plex/stream/{ticket}
GET /api/v1/session/me/wallboards/plex/stop/{ticket}
Authorization: Bearer <manager-or-approved-screen-session>
Each operation checks current authorization; streams also recheck the approved display and saved reference. Responses are private/no-store. Invalid requests return 400, invalid sessions 401, denied access 403, rate limits 429 with Retry-After, and unavailable/unconfigured Plex access 503. Search/start are rate limited. Tickets expire within eight hours; acquire a new one when required. Stop when hidden or removed. The official player loops videos/playlists with the configured sound, pauses hidden playback and retries temporary errors with backoff. Empty playlists have count 0. Transcoding is H.264/AAC HLS, up to 720p/4 Mbit/s, without subtitles; browser autoplay and server transcoding capacity apply. No watched-state or library writes occur.
Search videos for a wallboard widget — unreleased
SearchMyWallboardVideos — GET /api/v1/session/me/wallboards/videos/search is read-only and requires an active same-site manager with Wallboard1. Anonymous and screen sessions are denied. Authority is checked freshly before and after every search or cache read; neither search nor opening a citation writes a layout.
The required numeric widgetType is 39 (YouTube), 40 (Vimeo), 41 (Wistia) or 45 (Mux). Legacy Video 26 and other types are rejected. Optional query allows at most 256 raw/120 trimmed characters without controls. Empty and one-character queries return empty results without an external call. YouTube uses its explicitly enabled tenant API integration. Vimeo, Wistia and Mux use explicitly enabled public web discovery through the site's existing OpenAI integration. There is no fixed shared list or catalogue fallback.
The response contains at most 20 items, each with a plain-text name and complete canonical id, plus source: provider for YouTube or web for Vimeo/Wistia/Mux. Web items include sourceUrl, an actual search-tool source/citation URL validated for public HTTPS navigation; provider items omit it. Show this as a visible clickable citation beside the title, separately from selecting the video. A source may be a publisher's page rather than a playback URL: never extract the ID from it. Results retain discovery order and may be fewer than 20 because of validation and response-size bounds. A completed search with no eligible matches returns an empty result with its correct source.
The agent proposes video references from public pages, including pages with embedded videos. Every source URL must match actual tool evidence. Each video is independently checked through fixed official endpoints: Vimeo/Wistia oEmbed supplies identity and title; Mux requires an accessible tokenless video master manifest. If no structured citation title is available for Mux, the label is the agent's extraction of the cited page title and is not independently verified. Metadata checks do not independently verify the agent's association between a video and its cited publisher page. Search is incomplete and current metadata/manifest availability does not guarantee playback or permission to embed on your domain. Credential-bearing or signed playback references, unsupported formats and unavailable metadata are excluded. The API does not fetch arbitrary publisher pages or video segments. Only the public query is sent to discovery, without manager credentials, business tools, layout data or chat history.
Canonical references are YouTube's 11-character video ID; Vimeo's positive decimal ID with an optional / and 10 lowercase hexadecimal privacy-hash characters; Wistia's 10 lowercase letters/digits; or Mux's 16–128-character alphanumeric public playback ID, not an asset ID. Preserve Vimeo hashes. Treat names as text, never HTML. Only explicit selection saves the reference through the existing revision-checked widget operation; preserve the existing KID style and geometry. Never save source URLs or search titles in KIDs/layouts.
GET /api/v1/session/me/wallboards/videos/search?widgetType=40&query=flextouch
Authorization: Bearer <manager-token>
Illustrative response; search results and availability may change:
The overall API deadline is 35 seconds. Provider and AI calls have separate bounded budgets, concurrency limits and short tenant-bound caches; cancellation stops outstanding work. No automatic retries or other-tenant credential fallback. Missing configuration or an operational failure returns 503 video-search-unavailable, not an empty successful list. A limit/cooldown returns 429 video-search-rate-limited with Retry-After; wait before another request. Invalid type/query returns 400 video-search-invalid-type or video-search-invalid-query. Invalid sessions return 401; missing Wallboard1 or other authority failures return 403. Discard stale/type-changed results and preserve unsaved drafts on failures.
Location status — unreleased
eWidgetType.LiveLocation (42), shown as Location status, composes the existing Machine status widgets for every public unit in one selected location, including units without a current run. The wire identity stays 42. Store only the canonical same-site Location KID in k, with optional Kid.Style 0/1/2. Empty/style-only is unconfigured and makes no data requests. Bank, unit, cross-tenant and extra-metadata KIDs are rejected with 400 invalid-wallboard-widget. Saving and reading an approved display preserve current Wallboard1/resource grants, revisions, display binding and geometry.
{"t":42,"k":"A6Q1Eo7D0b4l","r":[0,0,30,30]}
GET /api/v1/public/widgets/progress/A6Q1Eo7D0b4l?pageSize=100
Reuse GetPublicScopedUnitProgress; no new data endpoint is needed. Follow nextCursor with the same location and page size until null: one location has at most 255 units, so at most three pages of 100. Keep numeric unit order and render all returned machines, without random selection or a running-only filter. Reuse the existing Started/Done progress calculation: missing or invalid timing stays unknown. This widget does not add cycle, offline, resident, payment, hierarchy or protected operational data to the public API. Existing public visibility still excludes deleted banks/locations/units and requires an enabled location; disabled units and child units remain included. An empty location returns an empty list. Refresh visible widgets from the first page every 60 seconds, pausing hidden/offscreen widgets; never present an interrupted page sequence as a complete location. Handle 400 as an invalid scope/page/cursor and 503 as unavailable, honoring Retry-After.
Because this uses the existing explicitly public data source, it may also be saved on the shared public wallboard with fresh whole-tenant authorization and its independent revision. The selected location KID is public layout content; no protected access is granted. Invalid or cross-tenant legacy type-42 KIDs are blanked in the anonymous layout response while preserving their rectangles. The public setting remains PortalWallboard for user 0/unit 0; no new setting or database write is introduced by reading the widget.
Reservation calendar — unreleased, available on alfa
eWidgetType.ReservationCalendar (29) is a read-only TV guide for one location. Store that location's canonical same-site KID in k, with optional Kid.Style 1/2. Empty/style-only KIDs remain unconfigured and make no calendar requests. Bank, unit, user and cross-tenant KIDs are not accepted. The current resource grant is checked when saving; normal layout revision and storage limits still apply.
{"t":29,"k":"A6Q1Eo7D0b4l","r":[0,0,30,30]}
This example targets Team location 4 in bank 2000; replace it with a location KID returned by your site's API. The portal commits its standard KID field on blur and preserves the widget's theme.
GetMyWallboardReservationCalendar — GET /api/v1/session/me/wallboards/reservation-calendar?locationKid=A6Q1Eo7D0b4l supplies manager previews. GetWallboardDisplayReservationCalendar — GET /api/v1/session/me/wallboards/display/{displayId}/reservation-calendar?locationKid=A6Q1Eo7D0b4l&portrait=false supplies approved screens. Both require a current manager, Wallboard1, Bookings1, Location Read, Unit Read, User Read, the matching location grant and existing directory/RetentionDays visibility. The selected screen's saved layout must contain a type-29 widget targeting that exact location; style is not an authorization grant. Screen sessions cannot use the manager-preview route. Device approval and the selected layout are rechecked after reading. No anonymous public reservation feed is created.
GET /api/v1/session/me/wallboards/reservation-calendar?locationKid=A6Q1Eo7D0b4l HTTP/1.1
Authorization: Bearer YOUR_MANAGER_SESSION
Accept-Language: en-GB
The response contains locationKid, timeZone, from, days (2), groups and reservations. Groups reuse the dated booking-calendar contract: canonical unit KIDs/plain names and concrete local dates with startMinute, durationMinutes and type (0 reservation period, 1 chance, 2 closed, 3 unknown). Only authorized units with configured calendars appear. Existing main-terminal opening hours and exceptions apply; invalid/missing calendars are omitted, never treated as available. Anonymous reservations contain only unitKid, startMinute (local wall-clock minutes since 2000-01-01) and durationMinutes. These coordinates are not UTC instants. No resident name, number, KID, payment or booking-write operation is exposed or read by this projection.
The widget shows only machines with a reservation overlapping the next rolling 24 local wall-clock hours, including ongoing reservations, using the existing two-local-day response. The six-hour axis may advance to the next reservation when no displayed machine has an ongoing reservation and the intervening schedule is fully known. No matching reservations produces a localized empty message. It follows light/dark styling and refreshes about once a minute while visible; hidden/removed widgets cancel pending reads. Reserved periods, chance periods, closed periods and unknown data remain distinct; the calendar is not a guarantee that a booking can be made.
Reads are bounded by a shared 15-second deadline, 5000 reservation rows and a 4 MiB response ceiling; overflow or incomplete/unavailable data fails rather than returning partial occupancy. The source is the tenant's current Log5 snapshot, not bank reservation history. Weekly positions below 10080 do not identify concrete dates: active weekly reservations make this projection unavailable until their controller semantics are supported. Errors: 400 invalid location KID, 401 invalid/inactive session, 403 denied scope/tab/operation or absent matching saved widget, 404 hidden/missing location, 409 layout conflict, 503 unavailable/unsupported reservation data. Do not interpret an error as free time. Packaged clients are refreshed at the next beta release.
Location map — unreleased, available on alfa
eWidgetType.LocationMap (36) displays all authorized locations that have valid stored coordinates, independently of purchase activity. It is available on all configured tenants with an empty or style-only KID. Host has no locations and returns an empty list.
GetMyWallboardLocationMap — GET /api/v1/session/me/wallboards/location-map supplies manager previews. GetWallboardDisplayLocationMap — GET /api/v1/session/me/wallboards/display/{displayId}/location-map?portrait=false supplies a selected display. Both require a current manager, valid credentials/API key, Wallboard1, Bank Read, Location Read and tenant/bank/location grants. Locations1 tab access is not required. An approved screen must remain bound to that exact display and its selected saved layout must contain type 36; device approval is checked again after reading data. Screens cannot use the manager-preview operation. These endpoints do not publish a public location catalogue.
The source is the existing tenant-bound Log24 location directory. Its scope, Enabled, Deleted and retention rules remain unchanged: limited grants cannot reveal sibling locations; a whole-tenant grant retains the directory's broader state visibility. Only canonical location KID, stored name and WGS84 latitude/longitude in decimal degrees are returned. Coordinates are decoded from stored microdegrees. Missing, invalid and placeholder 0,0 positions are omitted; no external geocoding or business-data writes occur.
GET https://alfa.api.team.kombine.technology/api/v1/session/me/wallboards/location-map
Authorization: Bearer <manager-session>
GET https://alfa.api.team.kombine.technology/api/v1/session/me/wallboards/display/Lobby/location-map?portrait=false
Authorization: Bearer <manager-or-approved-screen-session>
Response: {fetchedAtUtc,refreshAfterSeconds:60,items:[{kid,name,latitude,longitude}]}. The complete authorized catalogue is bounded to 10,000 rows before omitting invalid positions and the response to 4 MiB; exceeding either returns 503, never a partial map. The request deadline is 15 seconds and permission snapshots are at most 60 seconds old. Browser responses are no-store. Errors: 401 invalid/revoked session; 403 missing rights, mismatched screen or no matching widget; 409 invalid stored layouts; 503 location-map-unavailable for storage, deadline or size failure. Refresh only while visible, no faster than refreshAfterSeconds; on 401/403 clear the map and stop requests.
The official widget uses the existing Google Maps browser key and tenant light/dark map colors. It fits all valid coordinates initially, preserves subsequent user zoom/pan, and groups nearby locations when needed so large catalogues remain usable. A group represents every included location, not a truncated list. Names are rendered as text. Add a dark widget with {"t":36,"k":"2Is","r":[0,0,20,20]}. Client packages follow the next beta release.
Database load history — unreleased, available on alfa
Team (166), Electrolux (333), Hub (555) and Finelec (888) support eWidgetType.DatabaseLoadHistory (37), with an empty or style-only KID. This widget uses authenticated infrastructure data, not the anonymous public widget API. Other tenants cannot save or read this type. Reserved 11–20 and unimplemented 27–28, 30–35 and 42 remain unsupported.
GetMyWallboardDatabaseLoadHistory — GET /api/v1/session/me/wallboards/database-load-history supplies manager previews. GetWallboardDisplayDatabaseLoadHistory — GET /api/v1/session/me/wallboards/display/{displayId}/database-load-history?portrait=false supplies a selected display. Each read rechecks the active manager, credentials/API-key revocation and Wallboard1 before using the metrics cache. Hosting1, Managers Read and the whole-tenant KID grant are rechecked without the session cache before and after the read. A screen also needs its current durable approval for that exact display, and its selected saved layout must contain type 37. A screen cannot use the manager-preview operation.
The fixed source is the trusted tenant's configured DigitalOcean MySQL cluster. The preceding 24 hours include load1 from the load endpoint and CPU utilization from cpu_usage, both with aggregate=avg. Load1 is a one-minute load average; CPU is actual utilization in percent, not load1 divided by core count. Neither is individual banks' usage. Requests cannot select another provider, cluster, metric or time range. No SQL is executed and no credentials, provider IDs or provider labels are returned.
GET https://alfa.api.team.kombine.technology/api/v1/session/me/wallboards/database-load-history
Authorization: Bearer <manager-session>
GET https://alfa.api.team.kombine.technology/api/v1/session/me/wallboards/display/Lobby/database-load-history?portrait=false
Authorization: Bearer <manager-or-approved-screen-session>
Response: {fromUtc,toUtc,fetchedAtUtc,refreshAfterSeconds,series:[{points:[{timestampUtc,value}]}],cpuSeries:[{points:[{timestampUtc,value}]}]}. Dates are UTC; value may be null for a missing sample. Preserve separate series and gaps; an empty series is not zero load. Both successful and failed provider reads are cached for 60 seconds. Refresh no faster than refreshAfterSeconds, cancel while hidden and stop on access failure. Errors: 401 invalid/revoked session; 403 insufficient rights, mismatched screen or no matching widget; 404 unsupported tenant; 409 invalid-stored-wallboards for invalid saved layouts; 503 hosting-not-configured or hosting-unavailable. Browser responses are no-store. The official editor, previews and player use the bundled Chart.js with the widget's theme and container dimensions.
series retains the existing load1 series; the additional cpuSeries contains CPU percentages from 0 to 100. Invalid CPU samples become null. The two metrics may have different timestamps or sample counts. If one provider read fails, its array is empty and the other available metric is retained; both reads failing returns 503. Do not turn empty arrays or null samples into zero. Each metric is bounded to 64 series, 3,000 points per series and 15,000 samples in total (30,000 across both metrics); the complete serialized response is at most 4 MiB. An oversized metric is treated as unavailable while the other valid metric is retained. The chart uses a left load axis and a separate right CPU axis fixed at 0–100%, with distinct colors/line styles and labeled tooltips. Client packages follow the next beta release.
Database storage by bank — unreleased, available on alfa
eWidgetType.DatabaseBankStorage (38) is a protected Chart.js pie chart comparing banks by dataBytes + indexBytes. It is available on all configured tenants, with an empty or style-only KID. Host has no banks and returns an empty list. Reserved 11–20 and unimplemented 27–28, 30–35 and 42 remain unsupported.
GetMyWallboardBankStorage — GET /api/v1/session/me/wallboards/bank-storage supplies manager previews. GetWallboardDisplayBankStorage — GET /api/v1/session/me/wallboards/display/{displayId}/bank-storage?portrait=false supplies an approved display. Both require a current active manager, valid credentials/API key, Wallboard1, Bank Read and a whole-bank or whole-tenant KID grant. Location-only grants never expose a bank's total storage. The bounded authorization snapshot is cached for at most 60 seconds. Screens additionally require current approval for that exact display and type 38 in their selected saved layout; they cannot use the manager-preview route. Device approval is checked again before returning fetched data.
Data comes exclusively from the trusted tenant's bank-level Log24 states: eState.BytesData=171, BytesIndex=172 and BytesFree=173. Cleanup records these separately. Values are approximate allocation counts in bytes; BytesFree is allocated but unused table space, not remaining disk or plan capacity, and is excluded from the pie. No cleanup runs, information_schema reads or business writes are triggered. Existing bank-directory visibility, deletion and retention rules apply; whole-tenant visibility can include disabled/deleted banks. Up to 10,000 banks are supported; exceeding the bound fails without returning a partial total.
GET https://alfa.api.team.kombine.technology/api/v1/session/me/wallboards/bank-storage
Authorization: Bearer <manager-session>
GET https://alfa.api.team.kombine.technology/api/v1/session/me/wallboards/display/Lobby/bank-storage?portrait=false
Authorization: Bearer <manager-or-approved-screen-session>
Response: {fetchedAtUtc,refreshAfterSeconds,items:[{kid,name,dataBytes,indexBytes,freeBytes,dataRecordedAtUtc,indexRecordedAtUtc,freeRecordedAtUtc}]}. The three byte fields are nullable decimal strings to preserve 64-bit precision. Missing, malformed or negative values are null, never assumed zero. Sum data and index only when both are known. Dates are nullable UTC registration times for each stored state; they do not necessarily identify the last cleanup run. fetchedAtUtc is the response read time. Storage measurements are read again on every request; the 60-second interval is a client refresh recommendation, not a server data cache. The official chart shows the largest eight banks plus Other, with sizes, percentages and registration times; missing measurements are indicated separately. It follows the widget's light/dark theme and container size, refreshes every 60 seconds, pauses while hidden and stops polling on 401/403.
Responses are private/no-store. Errors: 401 invalid/revoked session; 403 denied bank access, mismatched screen or missing widget; 409 invalid-stored-wallboards; 503 unavailable storage or a complete bounded result cannot be produced. Client libraries will be refreshed at the next beta release.
Wallboard device pairing
Scanned personal layouts — unreleased, 29 October 2026: scanning a Wallboard QR in Wallboard1 saves its display ID in the signed-in manager's eSetting.WallBoards (3548), through AddMyManagerWallboard — POST /api/v1/session/me/wallboards. Send {"displayId":"Skærm 1"} with the manager bearer token; success is 200 {"code":"wallboard-saved"}. A new display gets an empty landscape layout (Id, empty Name, Portrait:false, Pages:[]). Existing recognized layouts, widgets and orientations are preserved and converted on save. A new ID is rejected if stored fields are unknown; rescanning an existing ID leaves the original text untouched. Rescanning an exact, case-sensitive ID adds no duplicate or history; concurrent additions merge inside the existing Log7 transaction. Only the authenticated manager's tenant-bound bank-zero setting is changed. No Tabs/Managers Write is required, and this preference grants no device approval or resource access; explicit device approval remains separate. Errors: 400 invalid-wallboard, 401 stale/inactive credentials, 403 screen session, 409 invalid-stored-wallboards or wallboards-limit (4092 stored characters), 503 unavailable/uncertain storage. Do not automatically retry failed writes. The scanner continues to pairing only after the save succeeds. Client packages follow the next beta release.
Watching committed layouts:GetMyManagerWallboards and GetPublicWallboard accept optional after=<64-character hexadecimal revision>. Supply the revision from that same operation. If it matches, the request waits for a committed change or at most eight seconds, then rereads; personal reads recheck authorization and anonymous reads retain the public projection. Private commits do not notify public watchers. Cancellation releases the bounded subscription; malformed revisions return 400 and exhausted capacity returns 429. Keep unchanged widget players and page timers running, cancel hidden views, and back off on errors. Existing requests without after remain immediate.
Public portal wallboard:GetPublicWallboard — GET /api/v1/public/wallboard is anonymous and reads the trusted tenant’s PortalWallboard from user 0 and unit 0. It returns a layout and revision, with an empty default if absent. Only public widget types are rendered; protected types are replaced by empty widgets without their KIDs. GetPublicWallboardEditor — GET /api/v1/session/me/wallboards/public and SavePublicWallboardEditor — PUT /api/v1/session/me/wallboards/public require a manager with Wallboard1 and an explicit whole-tenant grant. PUT accepts {"revision":"<revision>","wallboard":{...}}; a stale revision returns 409. It updates only the shared user-0 setting, never the manager’s personal wallboard. Protected widget types cannot be saved to the public layout. Anonymous responses do not provide access to protected widget APIs.
Move a public page to a private wallboard:MovePublicWallboardPage — POST /api/v1/session/me/wallboards/public/move-page requires the same fresh manager, Wallboard1 and whole-tenant authorization as the public editor. Send {"revision":"<personal revision>","publicRevision":"<public revision>","pageIndex":0,"targetPageIndex":0} for the personal Portal. To target an existing approved physical wallboard, also send targetDisplayId and portrait. Indexes are zero-based; the target index is the insertion position. Both revisions must match. The server moves the committed page unchanged, including its timing and legacy small widgets, in one transaction. It enforces the separate storage and page limits; any conflict, authorization failure or capacity rejection changes neither setting. The response contains the updated personal and public editor snapshots. After an uncertain response, reread both snapshots before taking further action. Set toPublic:true to move from the personal Portal into the public wallboard. For an existing physical source, also send sourceDisplayId and portrait; omit targetDisplayId. Only existing public widget types with valid canonical KIDs can be published. Protected types return 400 non-public-wallboard-widget without changing either setting. No widgets are removed and no screen IDs are added.
For a newly scanned screen, optionally send targetDisplayId with an existing screen ID from the destination layout. The screen is added to that layout under the same transaction lock; an unknown or ambiguous target or a screen already assigned to another layout returns 409 wallboard-target-conflict. Existing pages, widgets, permissions and device approval are unchanged. This requires Wallboard1.
Screen isolation — unreleased, 29 October 2026: a device session grants only its exact /wallboard/{displayId} page and the signed-device session flow. Attempting ordinary Portal pages, forms, downloads or interactive circuits signs out the screen cookie and redirects to /login?loggedOut=1 with HTTP 303, without executing the requested operation. Durable approval is preserved. In the API, a screen bearer is accepted only by explicitly designated Wallboard read/session endpoints, including GetCurrentManager — GET /api/v1/session/me and the display-scoped widget data endpoints documented above; ordinary business endpoints and manager-preview routes return 403. Its screen response contains the manager KID and wallboardDisplayId, but no manager permissions: tabs, tabDetails, resourceGrants, operationPermissions and navigationBanks are empty, hasBankAccess is false, personal display values are empty/default and database/gravatar values are null. Ordinary manager sessions are unchanged. Use a normal manager login for Portal administration; never reuse the screen bearer for business data. Durable device approval and its revocation checks remain unchanged.
A screen can use an existing manager session, including one obtained with LoginManager and {kid, apiKey}. Do not put the API key, manager token or device code in a QR code, URL or public Wallboard mapping. This is a dedicated device-pairing API, not an OAuth server.
New pairings reject displayId values that collide with the standalone Wallboard host's routes or root static assets, case-insensitively: for example api, swagger, health, wallboard-context.js and favicon.svg, including asset .gz/.br variants. A reserved ID returns 400; choose another ID. Existing approved devices and stored layouts keep their identities and normal authorization checks.
StartWallboardPairing: anonymous POST /api/v1/wallboard/pairings with {"displayId":"Screen 1","publicKey":"<base64 SPKI>"}. Keep the returned deviceCode private. The independent random pairingId may appear in a QR code. The pairing expires after five minutes; poll no faster than intervalSeconds (5 seconds).
GetWallboardPairing: authenticated GET /api/v1/wallboard/pairings/{pairingId} returns the display ID and expiry. Ask the manager to check the physical screen and the first six characters of its pairing ID.
ApproveWallboardPairing: after explicit confirmation, send authenticated POST /api/v1/wallboard/pairings/{pairingId}/approve, with an optional JSON body (no body remains supported). It returns 204. Approval is bound to this API's configured tenant and environment.
RedeemWallboardPairing: anonymous POST /api/v1/wallboard/pairings/{pairingId}/token with {"deviceCode":"<private device code>"}. Status is pending, approved with accessToken and expiresIn, or expired. Successful redemption is atomic and one-use. A wrong secret, unknown pairing, replay or revoked approving account returns expired.
POST https://beta.api.team.kombine.technology/api/v1/wallboard/pairings
Content-Type: application/json
{"displayId":"Screen 1","publicKey":"<base64 SPKI>"}
POST https://beta.api.team.kombine.technology/api/v1/wallboard/pairings/<pairingId>/approve
Authorization: Bearer <current manager session>
Permanent device approval: approval has no automatic expiry and no maximum offline duration. The browser generates an ECDSA P-256 signing key and retains the non-exportable private CryptoKey in IndexedDB, independently of the login cookie. Send the public key as standard base64 DER SubjectPublicKeyInfo in the required publicKey field of StartWallboardPairing. Save the returned pairingId as the device ID before redemption. After approval, the same device can reconnect after a month or years powered off.
ChallengeWallboardDevice: anonymous POST /api/v1/wallboard/devices/{deviceId}/challenge returns {challenge,message,expiresIn}. Sign the exact UTF-8 message with ECDSA P-256/SHA-256 and encode the 64-byte P1363 signature as unpadded base64url. ResumeWallboardSession: anonymous POST /api/v1/wallboard/devices/{deviceId}/session with {"challenge":"<challenge>","signature":"<signature>"} returns approved/expired, or retry without a token when a correctly signed challenge has expired, been consumed or been replaced by another tab. For retry, retain the device key and approved ID, wait briefly, then obtain and sign a fresh challenge; do not start QR pairing. The challenge is single-use and expires in two minutes. Device approval itself never expires.
Approved redemption and resume responses include displayId from the stored device approval. Bind the screen session to that exact, case-sensitive ID and reject a different URL ID, even when the browser already has a valid screen cookie. For example, approval for a does not approve b, d or A. Compare the decoded route value; encode it once when building the URL. Existing durable approvals remain valid. GetCurrentManager (GET /api/v1/session/me) returns wallboardDisplayId from the registered device for screen tokens, including older protected tokens; it is null for ordinary managers. This binds an older screen cookie without another scan. After session expiry, the original durable device proof obtains a new bound session.
Each screen bearer and its cookie last one hour. On expiry or browser restart the screen automatically obtains another session by signing a fresh challenge, without the manager's original session or API key. Clearing/losing the browser's stored key requires pairing again. Password/account revocation and API-key replacement still invalidate applicable grants; tenant isolation and credential/account checks remain. Ordinary business reads and writes, bearer renewal and further device approvals are forbidden for screen sessions. RevokeWallboardDevice: authenticated DELETE /api/v1/wallboard/devices/{deviceId} returns 204 only for the manager who approved it; missing/other-owned devices return 404. Revocation also invalidates existing device bearers on subsequent API requests. The screen profile grants no ordinary Portal access.
If the original redemption response is lost, recover with a signed device challenge. Network failures are retried automatically without deleting device approval. Keep all historical API Data Protection keys required to decrypt durable approvals.
Errors: 403 for a disallowed approver/write; 404 for missing/expired pairing details; 409 for an expired/already approved pairing; 429 with Retry-After for rate limits (six starts/approvals and 120 polls/details per minute per instance/IP); 503 when storage/account validation is unavailable.
The official portal keeps the device code in a protected Secure, HttpOnly, SameSite=Strict cookie, protects all browser POSTs against CSRF, and stores the final API bearer in its protected login cookie. The public mapping targets https://beta.{tenant}.kombine.technology/wallboard/{Id}. Before login the screen shows a pairing QR; after login it shows only a black page, Kombine logo, the manager's Kid.ToUserId and the display ID, with the tenant favicon. Both document.title and window.status contain identical JSON, for example {"watchdog":12345,"blank":false}, updated once per second. The lowercase watchdog value is Math.floor(performance.now()), the monotonic page tick count in milliseconds; lowercase blank is boolean false. There is no visible clock or status bar. Permanent pairing is available in beta (release 5c77c204, 29 October 2026); Portal production is pending. The one-scan/location extension below is local alfa only.
One scan and automatic phone location — alfa, not released to beta/production
The scanner accepts both https://wallboard.kombine.equipment/{Id} and https://alfa.wallboard.kombine.equipment/{Id}. The ID is required. Each mapping is saved through the API on the scanned Wallboard host, while its destination comes from the signed-in Portal tenant/environment. Wallboard has no beta hostname.
Scan the original Wallboard QR once in Wallboard1. In alfa the screen stays on Wallboard until approval; the QR has a short, unpredictable fragment (old #pair= links still work) for that physical browser. Compare its six-character code. Portal approves the screen’s public key, then saves the destination and phone location centrally in Wallboard. A single-use signed proof opens the Portal session without a second QR. Plain ID links are accepted, with code selection if multiple devices share the ID. External HTTP/HTTPS forwarding, for example https://dr.dk, is unchanged.
FindWallboardPairings: authenticated GET /api/v1/wallboard/pairings?displayId=Screen%201 returns an array of up to ten unapproved, unexpired WallboardPairingInfo objects in this tenant/environment, newest first. Matching is exact and case-sensitive. No matches returns []. Poll every three seconds; do not approve automatically.
The QR scanner in Wallboard1 always requests the scanning phone’s location. Browser permission is still required. Denial or timeout continues without location. ApproveWallboardPairing accepts {"location":{"latitude":55.67,"longitude":12.56,"accuracyMeters":18,"capturedAt":"2026-10-29T12:00:00Z"}}; replace the example timestamp with the actual UTC capture time. Coordinates must be finite and within latitude ±90 / longitude ±180; accuracy must be finite, nonnegative and at most 10000000 metres. Capture must be within ten minutes, with up to one minute future clock skew. Invalid location returns 400. This is an unverified phone measurement, not screen GPS. There is no portal switch to disable location. The captured position is saved automatically when the manager explicitly approves the screen.
GetWallboardDevice: authenticated GET /api/v1/wallboard/devices/{deviceId} returns {deviceId,displayId,createdAt,location} only to the approving active manager. Old/no-location approvals return location:null. Other-owner and unknown devices return 404; anonymous requests return 401 and screen/local sessions 403. Location is encrypted with the approval, never included in public URL mappings, QR data, URLs or screen tokens. It remains until device revocation deletes that registration. No database schema migration is required. Packaged clients will be regenerated at the next beta release.
The central extension requires separate Wallboard registration tables and the matching Portal Web bridge at release; it is currently local alfa only. Location is also saved privately in Wallboard and is not returned by its public mapping API. Portal device revocation still denies sessions; it does not automatically erase the separate central location record.
No request body is required. Replace the stored token and deadline only after success. The API rechecks the same site, active account and password stamp through its bounded snapshot (at most 60 seconds); renewal adds no Tab, KID or operation permissions. Local-development sessions remain restricted to Development and direct loopback connections. HTTP 401 requires login; 429 requires waiting for Retry-After; 503 means account storage is unavailable. A failed renewal does not extend the old token. Avoid parallel renewals and ignore late responses belonging to an earlier login.
The official portal uses a persistent, protected cookie and renews both cookie and API token after visible-page mouse, keyboard or scroll activity, at most once per minute. An idle open tab, public statistics and background requests do not renew it. Logout removes the browser cookie. Existing one-hour sessions keep their old deadline; log in again to start the new ten-day portal session. Generated clients and downloadable packages are synchronized in version 0.4.2. Packaged clients do not renew automatically.
A complete PowerShell 7 example
Copy this block into PowerShell 7. The dialog asks for the manager email and password. It displays the profile without printing the password or token. For local development, trust the .NET development certificate using dotnet dev-certs https --trust.
Unreleased. RequestManagerSignUp (POST /api/v1/session/signup) requires email, name, organisation, password and confirmPassword. Name/organisation: 1–200 characters without controls; email: plain ASCII internet address, max 254. Matching passwords: 12–128 printable ASCII characters without leading/trailing spaces. Optional language: exactly lowercase en, da or es. Omit it or send null for English. Empty strings, whitespace, regional tags, uppercase and other values return HTTP 400 ValidationProblemDetails with errors.Language before account creation or email queueing. The trusted site selects the tenant; unknown fields are rejected.
POST /api/v1/session/signup
Content-Type: application/json
{"email":"person@arendt.dk","name":"Example Name","organisation":"Example Organisation","password":"YOUR_NEW_PASSWORD","confirmPassword":"YOUR_NEW_PASSWORD","language":"en"}
POST /api/v1/session/signup-confirmation
Content-Type: application/json
{"token":"TOKEN_FROM_EMAIL"}
The API allocates a never-used manager identity under the shared tenant lock and atomically stores profile/password hash, pending marker, Enabled=0 and all nine operation masks=0 in Log7 together with verification mail in Mails. The mail UserId is this manager's identity. Mail-queue failure rolls back creation. No tabs, scopes or roles are assigned; the account cannot log in before verification. 202 accepted confirms processing, not delivery. Existing addresses silently return accepted. An untouched pending account resubmitted with its correct password receives a refreshed link using the same identity; other existing accounts remain unchanged.
ConfirmManagerSignUp (POST /api/v1/session/signup-confirmation) accepts only token. Explicit POST verifies the email and activates the existing pending account; it does not create another account or choose/change a password. Proof is bound to tenant/environment and current credential/pending/Enabled revisions, expires in 30 minutes and is single-use. 200 email-verified issues no session. Self-registration itself grants no business access. Authorized administrators may separately assign or revoke access while verification is pending. Confirmation preserves those changes and grants no permissions itself. Log in normally afterwards.
400 invalid-profile or invalid-password: correct input. 400 invalid-signup-token: invalid, expired, reused or altered account proof. Request a new link with the original credentials for a pending account. 429: wait for Retry-After. 503 signup-unavailable: uncertain outcome; never automatically retry. Never log bodies, tokens or passwords. Two requests per email per 15 minutes, silently throttled. Only exact domains nortec.dk, kombinetech.com and arendt.dk currently receive proofs; others return 400 email-delivery-restricted without creation/mail. Cleanup of abandoned pending managers is not implemented yet. Clients are updated during beta preparation.
Personal manager settings
GetMyManagerProfile and GetMyManagerTabs use the site's read connection and work without a configured write connection or MySQL write privileges. canEdit describes the manager's authorization, not the database account's privileges. Saving attempts SQL using the tenant's explicit Write connection, or its regular connection when no separate writer is configured; MySQL enforces the necessary privileges regardless of the account name; unavailable writes return 503 and must not be retried automatically.
The portal opens /my-settings from the signed-in manager icon. Integrations use the same public operations below. Except for redeeming an emailed confirmation token, all require an active, tenant-bound manager bearer session with a current credential stamp. They operate exclusively on that session's manager. Profile, email and password operations need no business Tabs, Kids or Managers Write. Changing your own tabs requires an explicit all-banks KID grant as described below. None of these operations change KID scopes, operation permissions, account state or other users. Administrative self-edit restrictions on the manager directory remain in force.
Operation ID
HTTP
GetMyManagerProfile
GET /api/v1/session/me/profile
SetMyManagerProfileField
POST /api/v1/session/me/profile/{field}
GetMyManagerTabs
GET /api/v1/session/me/tabs
SetMyManagerTab
POST /api/v1/session/me/tabs/{tabId}
RequestMyManagerEmailVerification
POST /api/v1/session/me/email-verification
ConfirmMyManagerEmail
POST /api/v1/session/me/email-confirmation
ChangeMyManagerPassword
POST /api/v1/session/me/password
Profile, icon and theme
The profile response contains kid, name, organisation, iconKid, email, emailVerified, themeMode, iconSet, retentionDays, language, dateFormat, numberFormat, lineSpacing, portalMaxOpenBanks, revision, availableIcons. No password hash or internal proof is exposed. The icon list contains person icons, with an existing non-person icon first when necessary. Writes accept only the exact field names Name, Organisation, Icon, ThemeMode, IconSet, Language, DateFormat, NumberFormat, LineSpacing, PortalMaxOpenBanks and RetentionDays. Name/organisation accept strings up to 200 characters without controls; new icons must belong to the person catalog; themeMode is numeric System=0, Light=1, Dark=2. RetentionDays requires a JSON integer from 0 to 2147483647: days you may see deleted records within your existing access. 0 hides deleted records. This changes visibility, not physical deletion; Tabs, Kids and operation permissions still apply. The response field is retentionDays; missing stored values default to 10 days; invalid values return 0. Explicit 0 is preserved.
Personal presentation preferences: both GetMyManagerProfile and GetCurrentManager return language (numeric eLanguage, null for automatic), dateFormat and numberFormat. Save exact fields Language, DateFormat or NumberFormat with the current profile revision using POST /api/v1/session/me/profile/{field}. Language accepts 0–15 (Danish=0, English=1, EnglishEU=7, Croatian=15); Last/None/All are rejected. Null restores browser/tenant selection. DateFormat accepts an empty string or dd-MM-yyyy, dd.MM.yyyy, dd/MM/yyyy, MM/dd/yyyy, yyyy-MM-dd. Append HH:mm for a 24-hour clock or hh:mm tt for a 12-hour clock with AM/PM, for example dd/MM/yyyy hh:mm tt. Existing date-only values keep the language’s clock format. This controls presentation only; date-only displays remain dates and time zones are unchanged. NumberFormat accepts an empty string or da-DK, en-GB, sv-SE, de-DE, fr-FR, ar-SA. Empty formats follow the language. No access grants, currency, protocol numbers or timestamps change. Personal language overrides the Washco default when explicitly chosen. An active own-account session is required; stale revision returns 409; invalid choices return 400. Reread after a conflict; never automatically overwrite another session’s changes.
LineSpacing is your personal vertical-spacing factor for tables and lists across portal pages. POST /api/v1/session/me/profile/LineSpacing with {"revision":"CURRENT_PROFILE_REVISION","value":1.5}. The JSON value must be one of 0.75, 1, 1.25, 1.5, 1.75 or 2. Both GetMyManagerProfile and GetCurrentManager return lineSpacing; missing/invalid stored values return 1. Default 1 preserves existing spacing. It changes screen presentation only, without changing fonts, navigation, printing, data or permissions. Values are persisted in the authenticated manager’s tenant-bound bank-zero Log7 using the same revision, credential and concurrency checks as other personal preferences. Invalid choices return 400; stale revisions return 409. Reload the portal after an acknowledged change.
PortalMaxOpenBanks is the maximum number of banks in your workspace. POST /api/v1/session/me/profile/PortalMaxOpenBanks with {"revision":"CURRENT_PROFILE_REVISION","value":3}, or use "value":null to remove the limit. Accepts any signed 32-bit JSON integer. Only positive values impose a limit; 0 and negative values mean unlimited and return null. GetMyManagerProfile and GetCurrentManager return nullable portalMaxOpenBanks. Missing or invalid stored values, including NaN, return null and impose no limit. The portal keeps the newest added banks at the top and closes excess branches from the bottom, including immediately after reducing the limit. Closing a workspace branch does not delete bank data or change permissions. Existing Tab/KID/operation checks remain mandatory. Values are saved to the authenticated manager’s tenant-bound bank-zero Log7 with the existing revision and credential checks. Invalid writes return 400; stale revisions return 409. Read a fresh profile/revision and retry after resolving a conflict. Reload the portal after an acknowledged change.
IconSet stores your personal icon-set preference as the exact JSON string "g" or "line". Both GetMyManagerProfile and GetCurrentManager return iconSet; missing or unsupported stored values return line; an explicitly saved g is preserved. The portal applies this choice to navigation, headings, lists and saved workspace links. Use the unchanged API-provided IconKid in /api/v1/icon/{iconSet}/{kid}.svg; the existing cross-set fallback still applies when an asset is missing. This preference requires only your active own-account session and does not grant business access.
POST /api/v1/session/me/profile/IconSet
Authorization: Bearer YOUR_MANAGER_TOKEN
Content-Type: application/json
{"revision":"REVISION_FROM_GET_MY_MANAGER_PROFILE","value":"line"}
Use the returned revision for the next save. Unsupported values or JSON types return 400; a stale revision returns 409: reread before retrying manually. Inactive sessions return 401; on 503 or a network failure keep the last confirmed preference and reread before retrying an uncertain write. Changing this preference does not change icon identities or image cache rules.
Send the last acknowledged revision with one value. A successful write returns the complete acknowledged profile and a new revision; do not mark a selection saved before this response. HTTP 409 profile-conflict requires a fresh read and a user decision before overwriting. The existing SetCurrentManagerTheme operation also remains available.
GetMyManagerTabs returns kid, tabs, availableTabs, revision, canEdit; each tab has a stable numeric id and enum-derived name. Any active manager can read their own selection. canEdit requires an explicit grant for the site's whole tenant (all banks and locations). Individual bank/location grants do not qualify, even if they cover every current bank. No Managers tab or Managers Write is required. Tabs do not grant operation permissions, and unimplemented tabs remain hidden from the workspace.
Choose a tabId from availableTabs, then send only boolean enabled and the last tab revision (64 hexadecimal characters). This revision is separate from the profile revision. The session identifies the manager; no manager/tenant selector is accepted. The current credential and all-banks grant are rechecked inside the Log7 transaction. Unknown numeric stored tabs are preserved, and unchanged selections create no history. Any own tab, including Managers, can be removed and restored while all-banks access remains.
GET /api/v1/session/me/tabs
Authorization: Bearer ACCESS_TOKEN
POST /api/v1/session/me/tabs/60
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{"revision":"REVISION_FROM_GET_MY_MANAGER_TABS","enabled":true}
HTTP 200 returns the complete acknowledged tab response. HTTP 400 means an invalid request/tab; 401 means an invalid or revoked session; 403 missing-tenant-access means the all-banks grant is absent; 409 tabs-conflict or invalid-stored-tabs requires a fresh read and a user decision. A network error or 503 can have an uncertain outcome: never retry automatically. This instance invalidates its permission cache immediately; other instances refresh within 60 seconds. The portal refreshes workspace tabs immediately after the confirmed save, including open bank branches, without replacing personal-setting drafts. If navigation cannot be refreshed, the saved selection is retained and a Reload link is shown.
Workspace refresh (unreleased): After a confirmed tab save, call GetCurrentManager — GET /api/v1/session/me with the optional refresh=true query parameter. This refreshes the authenticated manager's account snapshot on the responding API instance before validating credentials and returning navigation, even when the write reached another instance. The Portal uses this for the workspace and its open bank branches. Ordinary reads keep the 60-second cache; this does not renew the session or invalidate business-data caches. On 401 sign in again; on 503 retain the confirmed selection and offer a manual reload. Never repeat the committed write.
GET /api/v1/session/me?refresh=true
Authorization: Bearer ACCESS_TOKEN
Verified email changes
Request verification with the new email and the current password, including for local development sessions. Optional language is en (default), da or es. HTTP 202 email-verification-queued confirms the queue commit, not delivery. The existing sign-in address remains unchanged until an explicit confirmation POST. The same flow can verify an existing address.
POST /api/v1/session/me/email-verification
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{"email":"alex@nortec.dk","currentPassword":"CURRENT_PASSWORD","language":"en"}
POST /api/v1/session/me/email-confirmation
Content-Type: application/json
{"token":"TOKEN_FROM_EMAIL_FRAGMENT"}
The trusted portal link opens /verify-email#token=…, expires after 30 minutes and is single-use. No request may supply a return URL or target identity. The portal removes the fragment and submits the token through its CSRF-protected form; GET requests never mutate accounts. Confirmation requires no bearer, since the protected token grants only that exact address change. It is tenant/environment-bound and tied to email, password and confirmation log versions. Changes to these values invalidate outstanding proofs, even if a previous value is later restored. Among concurrent proofs, the first successful confirmation invalidates the rest.
HTTP 200 email-verified atomically saves the address and its version-bound proof, and queues a notification to the former valid address. emailVerified becomes false if an administrator later changes the address; old or manually assigned flags are not treated as this proof. Existing sessions keep their current expiry and permissions; use the verified address on the next login.
Development delivery restriction: only exact domains nortec.dk, kombinetech.com and arendt.dk can currently receive a verification link. Other addresses return 400 email-delivery-restricted without changing the account or queuing a proof. Mail redirected to the development inbox cannot prove ownership of another address. Notifications still follow the central delivery policy: other recipients go to jens@arendt.dk, with no Cc/Bcc.
Password changes
POST /api/v1/session/me/password
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{"currentPassword":"CURRENT_PASSWORD","password":"NEW_PASSWORD","confirmPassword":"NEW_PASSWORD","language":"en"}
Supply the current password and matching new entries. New passwords must differ from the current password and contain 12–128 printable ASCII characters without leading/trailing spaces, preserving shared legacy login compatibility. HTTP 200 password-changed commits password history and notification mail together. Discard the old bearer and sign in again. The portal signs out immediately after success; other API instances can cache the previous credentials for up to 60 seconds. This is password reauthentication and confirmation, not two-factor login.
Errors and integration limits
400 codes include invalid-profile, invalid-email, email-already-verified, current-password-invalid, invalid-password, password-unchanged and invalid-email-token. An invalid email token may be expired, used, stale, from another site, or bound to an inactive account. Framework validation failures use ValidationProblemDetails; unknown request members are rejected. 401 requires fresh login; 409 requires a profile reload; 429 means a rate limit; 503 account-unavailable means unavailable or uncertain storage.
Email requests and password changes each allow two attempts per account per 15 minutes per API instance, plus the shared recovery IP limit (10/minute). Confirmation uses the IP limit. All writes recheck the current account inside the storage transaction, with a 12-second deadline. All responses use no-store. Never log passwords, full request bodies or tokens. Never automatically retry an uncertain mutation; first check your profile or try normal login. Mail delivery depends on the existing asynchronous worker. Generated clients and downloadable packages are synchronized in version 0.4.2. These endpoints are new; no existing contract was renamed.
Forgotten passwords
RequestManagerPasswordReset and ResetManagerPassword are anonymous HTTPS operations. The API host selects the tenant. Recovery works only for one unambiguous, active manager account; it never grants Tabs, Kids or operation permissions.
Temporary development delivery restriction: a single plain email address on exactly nortec.dk, kombinetech.com or arendt.dk receives directly. All other recipients are replaced with jens@arendt.dk. Domain matching is case-insensitive; subdomains and recipient lists are not allowed through. Cc and Bcc are always cleared. The submitted email still identifies the original manager. This restriction applies in all environments and has no configuration override.
POST /api/v1/session/forgot-password
Content-Type: application/json
{"email":"manager@example.com","language":"en"}
The response is HTTP 202 {"code":"accepted"} for existing, unknown, ambiguous, disabled, deleted and per-address throttled accounts. There is no token in the response. The email contains a single-use link that expires after 30 minutes. Language can be en (default), da or es. Delivery is asynchronous; acceptance is not a delivery receipt.
POST /api/v1/session/reset-password
Content-Type: application/json
{"token":"TOKEN_FROM_EMAIL","password":"A new example password!","confirmPassword":"A new example password!"}
Use 12–128 printable ASCII characters with no leading/trailing spaces, and a password different from the current one. This restriction avoids silent character replacement by the existing shared password hash. Passwords remain compatible with normal login. HTTP 200 {"code":"password-reset"} confirms the password history and notification were committed together. Sign in normally; recovery does not automatically create a session. Other API instances may retain a previously valid session snapshot for up to one minute.
HTTP 400 invalid-password means a policy/confirmation failure; invalid-reset covers expired, already used, wrong-tenant, changed-account or invalid links, an inactive account, and an unchanged password. Request a new link when needed. Invalid JSON/field validation also returns 400 validation details. HTTP 429 includes Retry-After; HTTP 503 means configuration/storage is unavailable. Do not automatically retry an uncertain password write: try signing in or request another link. Never log tokens or request bodies.
The portal reads the email token from a URL fragment into a CSRF-protected POST form and removes the fragment from the address bar. Reset-page responses use no-store and no-referrer. Generated clients and downloadable packages are synchronized in version 0.4.2.
Manager invitations
The invitation includes the recipient's readable API login username, links to this tenant's API Swagger, guide and examples in the same environment, and a link to My settings. It explains how to generate and securely copy a personal API key, log in with kid/apiKey using LoginManager, and authorize Swagger with the returned accessToken. Sending the invitation does not generate or disclose an API key or change access.
InviteManager sends an existing manager an invitation to choose a password. Use an active manager bearer session with Managers1 (28), Managers Read and Write, and tenant-wide access. The own-profile lock also applies: editing your own account requires being the sole active manager with tenant-wide access. The API rechecks current credentials, permissions and target visibility inside the queue transaction.
POST /api/v1/managers/{managerKid}/invitation
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{"expectedRevision":"PROFILE_REVISION_FROM_GET_MANAGER","language":"en"}
Replace expectedRevision with the 64-character profileRevision returned by GetManager or the latest confirmed profile save. The target must be enabled, not deleted and have a valid saved email address. The request cannot override the recipient or portal URL. Language is en (default), da or es.
HTTP 202 {"code":"invitation-queued"} confirms the mail queue commit, not delivery. The same recipient restriction applies to invitations: only nortec.dk, kombinetech.com and arendt.dk receive directly; every other recipient goes to jens@arendt.dk, with Cc/Bcc cleared. Sending does not change the password, account state, Tabs, Kids or permissions. The link opens /accept-invitation, expires after 10 days and uses ResetManagerPassword with the password policy described above. Once the password is set, the link cannot be reused; normal login is required.
HTTP 400 means an invalid KID/request; 401 requires a new session; 403 means insufficient access or a locked own profile; 404 includes retention-hidden targets. HTTP 409 profile-conflict requires reloading the manager, while manager-invitation-invalid requires correcting the saved email or account state. HTTP 429 invitation-rate limits invitations to two per target per 15 minutes per API instance; follow Retry-After. HTTP 503 manager-invitation-unavailable indicates configuration/storage failure. Do not automatically retry uncertain responses because mail may already have been queued. Generated clients and downloadable packages are synchronized in version 0.4.2.
Client IP for server-side login
The API records the connection's IP address for rejected login attempts. A portal calling the API from its own server can additionally send its browser client's IPv4/IPv6 address in the optional X-Portal-Login-Client-IP header:
X-Portal-Login-Client-IP: 192.0.4.20
Send only an address observed by the portal server itself. The API treats this header as caller-reported metadata and records it separately from its own observed IP. It grants no permissions and does not change tenant binding, login restrictions or rate limits. Invalid or multiple addresses are ignored without changing the login response. Direct API clients do not need this header. Login responses and error handling remain unchanged; no diagnostics are returned in the response.
2. Understand the profile and permissions
This response is fictitious. Always use the actual values returned by the API.
Optional organisation from the manager's eSetting.Organisation in A{TenantId:D4}.Log7, BankId 0. Empty string when absent. The portal displays it below the name when nonblank. Display only; grants no access. Read in the same query and included in the manager's cache of at most 60 seconds.
retentionDays
Days after deletion during which the manager may see a deleted bank, location, unit, user or reservation. Read from eSetting.RetentionDays in A{TenantId:D4}.Log7, BankId 0. Missing, negative or invalid values default to 0, hiding deleted objects. This does not expand Kids, Tab or operation permissions and does not schedule physical deletion. Cached with the manager for at most 60 seconds. GetBankUsers enforces this limit. Future details, counts and searches must enforce it too.
kid
The manager ID as a string. Store and pass it unchanged. me returns only the signed-in manager. An ID does not grant access.
name, iconKid
Display name and icon identifier. The name can be empty. house can be displayed from /api/v1/icon/g/house.svg. Use a known valid icon name or a default icon; never insert raw markup or an arbitrary URL from the field.
tabs, tabDetails
Permitted pages, called Tabs. IDs correspond to eTab; names are stable enum identifiers, not translated page titles. Use IDs as keys and translate your own display text. Do not interpret unknown IDs as known permissions.
hasBankAccess
Whether at least one bank or location grant applies on this site. This is not blanket access to data.
resourceGrants
The specific areas the manager may access, explained below. Does not contain bank names or actual bank records.
operationPermissions
Four independent operation permissions: Bank, Location, Unit, User. Use the computed canRead, canWrite, canCreate flags to display relevant actions.
Portal database access
GetCurrentManager includes databaseAccess in the same profile request. Reuse the manager bearer session; no tenant or bank selector is accepted. This field is for display, for example in the workspace footer. canWrite=true means that the read/append privilege check on the tenant's shared Log7 and bank-zero Log7 succeeded. false means reading succeeds but the SQL privilege check is denied or the server is read-only. null or an absent field means unknown, never confirmed read-only access.
checkedAtUtc is the UTC start of the check. Known results are shared for 10 minutes per tenant/API instance; failures for one minute. There are no test writes or background polling. A failed check does not turn an otherwise valid profile response into a login failure. Existing session 401/503 rules still apply. This is an indicative check: privileges may differ between banks, and triggers/transactions are not checked. Administrator exceptions to read-only are not assumed. The field never grants access; operations still require the manager's account, Tab, KID and operation permissions.
Save your theme
GetCurrentManager returns themeMode, a numeric eThemeMode: System=0, Light=1, Dark=2. Missing or invalid stored values default to System. Apply this value when signing in, including on a different browser or device. System follows the device appearance; do not save the currently resolved light/dark color as the preference.
SetCurrentManagerTheme saves only the authenticated manager's own setting. It requires an active site-bound manager session, including the current account state and credential stamp. It does not require bank Tabs, resource grants or resident-write permission and does not grant business access. No tenant, bank, manager ID or KID override is accepted.
POST https://api.team.kombine.technology/api/v1/session/me/theme
Authorization: Bearer <accessToken>
Content-Type: application/json
{"themeMode":2}
Success is HTTP 200 with {"themeMode":2}. Repeating the same stored value does not create another history record. The saved value is included in the next profile read; the writing API instance invalidates its profile cache. Other instances can retain an older profile for up to 60 seconds. Responses are no-store.
Missing/unknown modes or extra request fields return 400; expired/revoked sessions return 401. Unavailable persistence, including an unconfigured write connection, returns 503. Keep the last confirmed preference and explain a failed save; do not claim that a local browser preview was saved. After an uncertain network result, re-read the profile before retrying. There is no background preference polling or cross-device push; a later login loads the stored setting. The operation uses the same HTTPS/JSON bearer contract for official portals, external portals and authorized agents.
Which banks and locations?
Each entry in resourceGrants applies only to its tenant. Multiple entries grant access to multiple areas.
scope = "Tenant": the KID identifies the site's entire tenant. Display “All banks” and “All locations”.
scope = "Bank": the KID identifies one bank and all its locations.
scope = "Location": the KID identifies one particular location in a bank.
scope describes the extent of access. Use the ID unchanged; do not derive permissions or object names from the string.
Working with KID strings
A KID is an ID returned in a kid field. Treat it as an ordinary string in every programming language. Store and send the complete value unchanged, preserving letter case. Do not decode, split or construct it yourself. No Kombine library is required.
Use the bank kid from navigationBanks for bank requests, the location kid from the location list for location requests, and the user kid from the user list for user requests. Use encodeURIComponent(kid) in JavaScript when inserting an ID into a URL. Use name for display and scope for the extent of access.
An ID is neither a login token nor a permission. The server checks the site and manager permissions on every protected request. An ID cannot switch tenants or grant more access.
This contract revision replaces the separate userId, tenantId, bankId, and locationId fields with KID strings. Update clients that used the old fields. Existing login and profile routes are unchanged.
What may the manager do?
Installer comes from eSetting.PermissionInstaller2 (3016), read from current bank-zero Log7. It is included in GetCurrentManager, GetManagers and GetManager. GetInstallers requires Installer Read, Installers1 and tenant-wide access; these flags do not grant permissions in other categories. Match permission entries by resource, not array position or a fixed category count.
The seven categories Managers, Bank, Location, Unit, User, Installer and Service use independent ePermission2 bits from PermissionManagers2/Bank2/Location2/Unit2/User2/Installer2/Service2. flags is the bitmask: Read=1, Write=2, Create=4, Delete=8, RenameExtrenatId=16, Rename=32. For example, 5 grants reading and creation, but neither writing nor deletion. No flag implies another.
Missing/empty values default to Read (1); explicit 0 grants nothing. Invalid values or unknown bits yield null and no access. Use canRead, canWrite, canCreate, canDelete, canRenameExternalId and canRename for display. The retained level field is enum text and may be numeric for combinations. Old Permission settings are not used. Tabs, KID scope and active account checks remain required; insufficient rights return HTTP 403. Managers flags do not introduce new manager operations.
Show “You do not have access to any banks yet” when hasBankAccess is false. Show “You do not have access to any Tabs yet” when tabs is empty. Both messages may apply. A network error or HTTP 503 must be shown as a retrieval error rather than missing permissions.
Client controls help the user navigate. The API must enforce account state, site, Tab, the actual object’s scope, and the operation before returning or changing business records. Editing client JSON or a link must never grant more access.
3. Errors and client actions
Check the HTTP status first. Login can return HTTP 403 with a stable code, for example {"code":"disabled"}. Other errors normally use Problem Details with status, title, and possibly traceId; validation errors can also contain errors. A proxy or web server can return an empty body or HTML, so error handling must not require JSON.
Status / code
Meaning
Client action
400
Invalid JSON, email, or missing fields.
Correct the input. Email is limited to 254 characters; password to 1,024.
401 on login
Credentials do not match a valid manager.
Show “Incorrect email or password.” Do not retry automatically.
401 on me
Missing, invalid, or expired token, or a changed account/password.
Discard the token and return to login. This response does not reveal the exact account state.
403 / disabled
The manager is disabled.
Explain that the manager is disabled and suggest contacting the administrator.
403 / deleted
The manager is deleted.
Explain that the manager is deleted and suggest contacting the administrator.
403 / account-settings
Enabled is missing or invalid, or a present Deleted value is invalid.
Explain that account setup is incomplete and needs administrator attention.
413 / 415
Oversized login body / unsupported content type.
Send only email and password as application/json. Login body limit: 8,192 bytes.
429
Too many login attempts.
Wait at least Retry-After seconds (currently 60). Default to 60 seconds if absent.
503
Required data cannot be loaded.
Display a temporary service error. Offer a retry after a pause.
Login reveals a 403 reason only after verifying the password. Translate the codes in your own interface. Do not depend on English error titles or a particular traceId.
4. Your own portal
Complete JavaScript example
Open the working JavaScript example. It includes API address, email, and password fields and buttons for status, login, profile refresh, and logout. It uses ordinary fetch without npm packages or a framework.
To use it in your portal, copy portal-api.mjs into your JavaScript folder. It is a small optional example; direct fetch calls also work, as shown below. Create one client per user and API site:
import { createPortalClient } from './portal-api.mjs';
const portal = createPortalClient('https://api.team.kombine.technology');
// Obtain email and password from your login form.
await portal.login(email, password);
const manager = await portal.getProfile();
// Display manager.name, manager.tabDetails, and manager.operationPermissions.
// Call portal.getProfile() for manual refresh and portal.logout() for logout.
Load your own script with <script type="module" src="./app.mjs"></script>. Host the example files on your own web server; do not open them using file:// or import the module directly from another API origin. The same module works in Node.js with built-in fetch. Server-side JavaScript does not need CORS.
The client keeps only the token in memory, reuses it, clears it after HTTP 401, and provides errors with status, code, and retryAfter for HTTP 429. Network, certificate, timeout, and CORS failures may have no HTTP status. There are no automatic retries or polling. Do not share a client instance between users on a Node.js server.
A portal with its own server
Have your server call the API and keep the access token in each user’s protected session. This is also how the official Blazor portal works. Never share one manager session between users. The browser uses your portal’s own cookie/login while your server sends the bearer token to the API. This does not require CORS.
A browser calling the API directly
Browse all examples and their API endpoints. The single-file Cycle viewer remembers login in this browser until logout or session expiry, storing only the bearer session, never the API key. It retains the last 16 documents in memory, uses public WashDoc widgets in grid view and an interactive Chart.js graph on selection. Public widget visibility is independent of manager access. Save cycles.html, run python -m http.server 8080 --bind 127.0.0.1 in its folder and open http://localhost:8080/cycles.html. Local localhost/127.0.0.1 port 8080 CORS applies only to LoginManager, RenewManagerSession, GetUnits, GetUnitDocuments and GetUnitDocumentGraph; public widgets retain anonymous GET CORS. Direct file opening supports demo only. Normal permissions apply. Available in each environment after deployment.
Shared portal graph component
The viewer loads the exact portal renderer and stylesheet from /components/cycle/js/cycle-component.mjs. Import mountCycleChart, fetch GET /api/v1/public/cycle-chart/presentation (GetCycleChartPresentation), then call mountCycleChart(host, { presentation, loadGraph, onError }). Pass the authenticated response’s Content-Language as Accept-Language when fetching presentation. loadGraph(signal) returns JSON from the authorized GetUnitDocumentGraph endpoint, checks response.ok and preserves error.status. Keep the bearer token in the caller; never put it in component URLs or DOM attributes. The return value provides ready and destroy(); destroy before changing document, removing the host or logging out. Running graphs refresh every 15 seconds in a visible tab; completed graphs stop. The shared renderer includes phase markers, a synchronized cursor, recorded details and state/setting selection. Static assets and presentation are anonymous GET reads with CORS; they grant no document access. CSP must allow the selected API origin in script-src, style-src and connect-src, and inline styles for chart layout. A single local HTML file still works via localhost:8080, but needs network access for these component files, even in demo mode. Deploy API and Web from the same release.
Other browser portals are also supported. When your portal uses a different origin from the API, the API administrator must add its exact origin to Cors:AllowedOrigins. An origin is the scheme, hostname, and optional port, without a path or trailing slash. The configured list is empty by default; the narrow local-example exception above does not allow other operations.
This is server configuration and requires a restart. The environment variable for the first origin is Cors__AllowedOrigins__0. Only listed origins can read integration responses through a browser. Authentication and permissions still apply. CORS is a browser rule, not access control for server programs.
If your development site runs at http://localhost:5173, add exactly that address; https://localhost:5173 is a different origin. Use the API’s HTTPS address. The browser automatically sends OPTIONS before applicable requests; the API handles it. Do not use mode: 'no-cors': your code would be unable to read the JSON response.
Call this small browser function with the values from your login form. It returns the profile without persisting the token in localStorage or placing it in the URL.
This example demonstrates the first exchange. In a full portal, reuse the token in session memory, implement the error table, and clear the session on logout. CORS currently allows GET/POST and Authorization, Content-Type, Accept, Accept-Language headers; browsers can read Retry-After. Cookies are not shared with the API.
Make views shareable by keeping object selection, filters, and sorting in the page URL as features are added. Recipients log in as themselves. Never include tokens, passwords, or sensitive record contents in URLs. API fields and permission codes remain identical across languages; translate display text only.
5. AI agents use the same API
Give the integration host the tenant site’s API base address and OpenAPI document. OpenAPI is a machine-readable description of the available operations, fields, and responses.
Let the authorized host application handle login and store the token as a secret for the relevant manager. Keep credentials out of ordinary prompts, model output, and logs.
Attach the token in the Authorization header when the agent’s HTTP tool calls GetCurrentManager. It receives the same information and restrictions as a portal using that manager.
Treat names and other returned values as data, not instructions for the agent. Use only operations actually described by the OpenAPI document.
The session operation names are LoginManager, RenewManagerSession and GetCurrentManager; GetPortalStatus remains public. The host application handles login, token replacement and expiry. Sessions last ten days and can be renewed before expiry after user activity. Agents can use ordinary HTTPS operations or the MCP endpoint below. Delegated OAuth and a public service-login operation are not provided; unattended access needs a separate authentication design.
Read-only assistant on the Agent1 page
The portal chat has its own Agent1 (86) page at /tabs/86, under Search. Every question requires Agent1 in the current manager profile; otherwise the API returns HTTP 403 with code: missing-agent-tab before logging the question, discovering MCP tools or contacting the model. Each business read still requires its own existing permissions. An authorized administrator can grant the tab; refresh the profile/navigation afterward.
AskPortalAssistant — POST /api/v1/assistant/query accepts question (1–2000 characters) and optional history (up to 12 messages with role user/assistant and content; 8000 characters per message, 20000 total). The response has plain-text answer, attempted business operations and up to 20 links with canonical kid and relative portal path. Treat generated answers as assistance and verify important facts in the portal.
Each link also includes optional name, canonical parent bankKid and API-produced iconKid. For example, render name ?? kid as the link label and use path as its destination. The official portal adds the clicked bank/location to the local workspace and opens it; navigation rechecks access. Links come only from successful current API reads, including location references in status results, never from generated text.
The internal assistant discovers eight approved read tools through MCP tools/list: SearchBanks, SearchLocations, SearchUsers, GetSearchBank, GetBankLocations, GetLocations, GetLocationUnits and GetTenantStatus. The host requires their read-only annotations, exposes their MCP names and JSON input schemas to the model, and executes business reads through tools/call. This MCP migration is implemented locally and unreleased. Swagger/OpenAPI remains available for exploration and contract tooling and supplies the server's shared MCP catalogue.
Each read uses your manager bearer session and the existing Tab, KID scope and Read permissions. The internal assistant grants no additional access and performs no writes, even though other authorized MCP clients can use the broader read/write catalogue. The portal server owns the MCP connection and keeps the token in HTTP headers; the model provider receives ordinary Responses function definitions and authorized results. Questions, supplied history and relevant authorized results are sent to OpenAI; credentials are never model input. When live diagnostics is enabled, the current question text is retained once in the authorized, process-local log buffer after session revalidation and before model use. The buffer expires after 15 minutes or at restart. History and answers are not included in that event. No server-side chat history is retained; store=false disables Responses application-state storage, not necessarily all provider retention.
The assistant uses reviewed instructions packaged with the API and can load three named skills: offline-installations, find-location and explain-balance. Skills grant no additional operations or permissions. The balance skill explains limitations: the chat catalogue currently contains no balance or account-transaction reads. Skill loading counts toward the seven model turns, not the eight business reads.
curl "$BASE/api/v1/assistant/query" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -H "Accept-Language: en-GB" \
--data '{"question":"Which of my sites are offline?","history":[]}'
Limits: eight business reads, seven model turns, 120 seconds, paged reads at most 50 rows and 48000 bytes per tool result. Non-paged overview endpoints retain their existing bounds. Oversized results are withheld as truncated; failed sources and hasMore are not proof of complete or healthy data. 400: invalid question/history. 401/403: session unavailable; sign in again or check permissions. 429: wait for Retry-After (six questions/minute per manager, four simultaneous requests per process). 503 with code=assistant-not-configured: ask the host administrator to activate it; other 503 errors indicate provider/network failure or timeout. Retry manually. This operation is server-to-server; it has no browser CORS policy. Existing session, error and language conventions apply. Generated clients and downloadable packages are synchronized at version 0.4.2.
6. Refreshing, database load, and hosting
Fetch once and reuse the response. One me request provides the profile, navigation, and all three access cards. Log in at session start rather than before each call. Manager snapshots are cached for up to 60 seconds per API instance. Concurrent lookups for the same manager share a refresh. There is no automatic database polling.
Changes to permissions, Kids, Tabs, Enabled, and Deleted can therefore take up to one minute to be observed on the next request. An idle page does not update automatically; reload it or offer a Refresh action. After cache expiry, unavailable data does not fall back to old grants. Avoid tight retry loops; for transient failures, consider waiting 5, 15, and 30 seconds, then displaying the failure.
Login currently permits 10 attempts per normalized email per minute and 120 per source IP per minute, per API instance. Server portals can share a source IP, so avoid unnecessary repeated logins. Hostnames and database details are not client credentials.
For the API host administrator
Host the API over HTTPS with the appropriate tenant binding, hostnames, database connection, and protected persistent Data Protection keys. Web and API must use the same tenant. External clients receive the API address and their manager access; database credentials stay on the server. Replicas for the same site need securely shared keys and coordinated login throttling. Caches remain local to each instance. Only trust forwarded headers from configured reverse proxies.
Swagger, OpenAPI, and the guides are included in published API output and controlled by ApiDocumentation:Enabled (default true). English is the primary documentation language at /docs (also /docs/en), with Danish at /docs/da and Spanish at /docs/es. Client packages use an English README.md and include README.da.md and README.es.md. These code changes do not themselves publish the API to the internet.
GET /api/v1/database/status is for operators only. Its separate diagnostics document requires a different credential: a JWT with scope portal.diagnostics. Manager tokens cannot access it. Use /api/v1/status or /health for normal availability checks without MySQL queries.
As the API grows
Implement new portal data and operations in the shared API before Web uses them, and document them here and in OpenAPI. External clients should tolerate additional JSON fields and future enum values without granting extra access. Do not silently change the meaning of existing v1 fields; incompatible contract changes require a new version. Large lists need server-side filtering and pagination when introduced.
Bank names in navigation
The existing GET /api/v1/session/me (GetCurrentManager) includes navigationBanks. Reuse your bearer token and read profile.navigationBanks in JavaScript. Each item has kid, name, and iconKid; no numeric identifiers or extra request are needed. Use the KID as the item identity and copy that exact string when sharing an identifier.
Labels require an active account, at least one permitted Tab, Bank Read, and a bank or location grant in this site. A location grant allows its parent bank's navigation label only, never all bank data. The array is empty for all-bank access (enumeration is deferred), no Tabs, no scopes, or invalid Bank permission. Each child Tab still requires its own authorization for actual operations.
Names and icons come from the site's Log24, EntryType Settings (2), LocationId 0, UnitId 0, using eSetting.Name (99) and Icon (37). Missing values are empty strings: show an unnamed-bank label and a local icon fallback. Render text as text, never HTML. For a safe icon identifier such as house, use /api/v1/icon/g/house.svg. The portal shows the bank KID on hover and offers a copy action on right-click.
Labels are cached for one minute per bank per API instance, shared between managers; cache misses are batched in groups of at most 64 banks. Authorization is rechecked independently with the bounded manager snapshot. No bank enumeration occurs for tenant-wide grants. A storage failure returns 503: do not interpret it as an empty permission list. Retry later; invalid/expired sessions return 401. Navigation labels do not implement bank detail or deleted-record listings.
tabDetails[].icon comes from AttributeMetaIcon on the corresponding eTab, for example bank_building. Use the same safe icon URL pattern as banks. An empty string means no icon; display a local fallback. Icons come from the shared enum without database queries.
userKid selects exactly one resident in the bank: await client.getBankUsers(bankKid, { userKid: residentKid }). Use a canonical User KID from a previous response. It must belong to the site tenant and specified bank and cannot be combined with filter or cursor (400). The same manager, Tab, User Read, location and RetentionDays checks apply. The response has zero or one item and no continuation cursors. Missing or invisible users return an empty list without revealing whether they exist. The portal shareable view uses /banks/{pageKid}, with both Tab=Users2 and the resident UserId in its bank page KID. Legacy ?resident={userKid} links redirect; browser workspace bookmarks grant no permissions.
Wildcards in filter: * matches zero or more characters and ? matches one character. Examples: filter=1568-*002* or filter=Anna?*. Matching remains substring-based in Number OR Name, including plain text without wildcards. Other characters, including SQL characters % and _, are literal. URL-encode the filter with URLSearchParams or encodeURIComponent. Matching runs in API memory against the existing cached index; no wildcard SQL is generated.
filter matches a substring in number OR name using culture-independent case-insensitive comparison. Maximum 200 characters; surrounding whitespace is trimmed. An empty filter returns the full authorized list. Filtering precedes paging and reuses the shared cached sorting index, including identity mode. Keep filter with the cursor; changing it requires a request without a cursor, otherwise 400 is returned. Permissions and RetentionDays still apply. Example: await client.getBankUsers(bankKid, { sort: 'name', direction: 'asc', filter: 'anna', pageSize: 25 }). URL-encode filter text. Shared links contain the search text.
iconKid contains the user setting eSetting.Icon (37), normalized to a valid eIcon name. Missing, empty, unknown values and none default to user. Stored enum names and numeric enum values are supported. Display it from /api/v1/icon/g/{iconKid}.svg. The icon is fetched with the page settings under the same authorization and cache; it adds no separate database query per user.
Set sort=number|name|location|deleted and direction=asc|desc. Ordering applies to the entire authorized list, including progressively loaded pages. Omitting sort preserves legacy identity order (asc only). Numeric numbers sort numerically before text numbers; names and text numbers use language-independent ordinal, case-insensitive comparison. Location means the lowest visible Access/NoAccess location number. Empty values and non-deleted users come first in ASC and last in DESC. Deleted users sort by deletion time. User identity breaks ties.
Keep sort, direction and pageSize during traversal. When changing order, restart without a cursor. A cursor for another sort or direction returns 400. Sorted cursors are positions in the current authorized list; data or permission changes can shift positions between requests. Shared links never grant the sender's permissions.
Sorting uses a shared four-setting index cached for up to 60 seconds across managers and sort choices. The API filters permissions and sorts in memory; only the selected page fetches the remaining details. There is no COUNT, SQL OFFSET or query per user. A cold cache scans the bank's ordinary users; very large banks may hit the timeout and return 503. Avoid immediate automatic retries. Identity mode retains its bounded 1,000-candidate scan and scanLimitReached behavior.
The official portal uses GetBankUsers for progressive loading while scrolling. External portals can do the same: request one nextCursor at a time, reuse the result and stop at null. Stop automatic loading on errors and offer an explicit retry. Every request is authorized, including cursors received in a shared link from a colleague.
Users in a bank (Users2)
GET /api/v1/banks/{bankKid}/users?pageSize=25 · operation GetBankUsers. Take the bank KID from navigationBanks or a Bank scope in resourceGrants. Send the manager bearer token. No separate tenant, bank or user IDs are accepted.
const page = await client.getBankUsers(bankKid, { pageSize: 25 });
for (const user of page.items) console.log(user.kid, user.name, user.number);
if (page.nextCursor) {
const next = await client.getBankUsers(bankKid, {
pageSize: 25, cursor: page.nextCursor
});
}
The response contains items, previousCursor, nextCursor and scanLimitReached. Each user has kid, name (99), number (1824), email (2800), deletedAt (1996, UTC or null), locations (1809, KID and Access/NoAccess), tags (2977, KID and eTagState) and attributes (2978, eUserAttribute name and value; negative means no numeric value). Missing text/lists are empty; missing Deleted means not deleted. Email is read from the current Log7 eSetting.Email value; both JSON strings and older plain text are decoded. This field is read-only and cannot be changed through profile.
sms is the resident’s current phone number from Log7 eSetting.SMS, decoded from a JSON string or legacy text without changing its formatting. Missing values are empty; older data may use 0 for no number. It is read with the other details under the same tab, read, resource and retention rules. This read-only field does not send texts or place calls. The portal uses mailto: and tel: for valid contact values; invalid values remain plain text. Link handling depends on the device’s mail and phone apps.
Requires an active manager, Users2 (53), User Read and a matching resource scope. Tenant/bank grants include ordinary bank users. Location grants include only users associated with at least one permitted location, in either Access or NoAccess state; other locations are removed from the response. Name, number, email, tags and attributes are shared bank-level user data. RetentionDays limits deleted-user visibility; malformed deletion settings hide the user. The inclusive eUserId.Users–UsersLast range excludes manager and service accounts.
pageSize is 1–200 (default 25). The default identity mode orders by ascending user identity. Copy each returned cursor unchanged; null means no continuation in that direction. Cursors can be shared, but never grant access. Recipients use their own permissions and may see different contents. Concurrent changes mean pages are not a frozen snapshot.
In identity mode, to limit MySQL load, batches are cached for at most 60 seconds, without a full count or OFFSET. At most 1,000 candidates are examined per request. With scanLimitReached=true, a page can be short or empty: follow its continuation cursor. Do not automatically poll every page.
400: invalid KID, cursor (restart at the first page). 401: sign in again. 403: missing Tab, scope or User Read. 503: temporary storage failure; show an error and retry later, not an empty list. Tokens are never included in shareable portal URLs. Browser JavaScript requires an allowed CORS origin as described above.
Users2: Each locations item also includes iconKid, the location eIcon name from eSetting.Icon in Log24. Missing or invalid icons default to house. Icons are cached for up to one minute. state remains Access or NoAccess. The portal displays the icon with state as a data attribute and location number/state/KID in its tooltip.
Bank overview locations
GET /api/v1/banks/{bankKid}/locations (operationId: GetBankLocations) returns an array of {kid,name,iconKid,enabled,deleted,deletedAt}. Use a plain bank KID and your manager bearer token.
Requires an active manager, at least one assigned Tab, Location Read (also included in Write/Create), and matching site/bank/location access. Location-only grants return only those locations. An explicit site-wide grant shows all location states, including disabled locations and deletions outside RetentionDays. Other grants show only Enabled exactly 1 and non-deleted locations or deletions within RetentionDays. Zero retention hides all deleted locations; malformed and future deletion values are hidden for limited grants. 400: invalid/wrong-site KID; 401: sign in again; 403: insufficient access; 503: retry later. Data is cached for up to 60 seconds; authorization is checked on every request. Results are ordered by location number, without pagination. Only locations with a Name, Icon, Deleted or Enabled setting in Log24 are discoverable. Missing or invalid icons default to house. Use kid as the location ID and name as its display name.
Status fields: enabled is true only for stored Enabled exactly 1; missing or invalid values mean false. deleted is true for a positive Deleted MS2000 value, false for zero (including missing), or null for malformed values. deletedAt is the UTC deletion timestamp, or null for zero or an unrepresentable value. Display inactive when enabled is false, otherwise deleted when deleted is true, otherwise active. Status never grants access; visibility is filtered by the API using the current manager scope and RetentionDays. These fields match GetLocations and come from the same cached Log24 read.
Location overview and units
GET /api/v1/locations/{locationKid}/units, operationId GetLocationUnits. Returns {location:{kid,name,iconKid},items:[{kid,name,iconKid,cycle,cycleText,unitType,unitTypeName,unitTypeSource}]}. Use a canonical location KID from the bank location list or a user's locations; user location entries now also include the location name.
Requires an active manager, at least one Tab, Location Read and Unit Read (Read must be explicitly set), plus access to this site and bank or exact location. Every request rechecks access. Both location and unit deletion follow RetentionDays; missing Deleted means not deleted. 400: invalid KID/site; 401: sign in again; 403: insufficient rights; 404: location missing or no longer visible; 503: retry later. At most 255 units, ordered by unit number without pagination. Empty items is a valid result.
Unit data from Log24 is cached for up to 10 seconds. Units need Name, Icon, Deleted, Cycle, UnitType or UnitType2 to be discoverable. Missing names are empty; missing/invalid unit icons use object_cube. Valid configured icons are preserved. The API includes the unit number in IconKid.Text; g/object_cube and line/object_cube display this text on the box face. The same default applies to unit overviews, documents, bookings and account entries. Web uses the shareable route /locations/{locationKid}. Workspace shortcuts are stored per manager and browser tab and never grant access; the cross only removes the shortcut.
Location weather (unreleased)
GetLocationWeather, GET /api/v1/locations/{locationKid}/weather, provides current Open-Meteo conditions through the same public Portal API used by the official portal. Reuse the manager bearer session and a canonical location KID from GetBankLocations. The trusted site determines the tenant. No provider key, address or coordinates are accepted from the caller.
Requires an active manager, at least one assigned Tab, Bank Read, Location Read, a matching site/bank/location grant and RetentionDays visibility. The location and parent bank must also pass the existing GetObjectAddress visibility checks. Neither Unit Read nor Write is required. Every request reauthorizes and reads the exact location’s own Log settings before looking up cached weather.
A complete, valid eSetting.Latitude/eSetting.Longitude pair (stored in integer millionths of degrees) takes precedence. Otherwise the API geocodes available Address and Zip using the existing site geocoder. Partial addresses and postal areas are approximate. Missing coordinates are never treated as zero or filled from a different object. This GET does not save geocoding results or change any settings.
The response contains locationKid, status, address, zip, positionSource and current. Status is Available, LocationUnknown (no resolvable position), or Unavailable (provider/configuration failure). current is null unless Available; positionSource is Coordinates, Address or null. Address and Zip may be empty. Available current data includes UTC observedAtUtc/retrievedAtUtc, temperatureCelsius, and nullable apparentTemperatureCelsius, windSpeedMetresPerSecond, precipitationMillimetres, relativeHumidityPercent, WMO weatherCode and isDay. Null means unknown. Never display missing weather as zero.
HTTP 400: invalid/foreign KID; 401: sign in again; 403: missing tab/scope/read permission; 404: missing or hidden location/parent; 503 with code location-weather-unavailable: storage failure or deadline. Keep the rest of the page usable and retry on a later navigation. Successful weather is cached for ten minutes per tenant, location and address revision; negative results for one minute. HTTP responses are no-store. Four provider lookups may run concurrently per process; the full request has a twelve-second deadline and no automatic retries. Weather refreshes on navigation, not continuously.
These are model conditions, not on-site measurements or a forecast card. Display attribution with links to Open-Meteo and CC BY 4.0. Provider fields and WMO codes follow the Open-Meteo documentation. This new operation is unreleased; packaged clients will be updated during beta preparation.
Location opening hours
GET /api/v1/locations/{locationKid}/opening-hours, operationId GetLocationOpeningHours, returns the effective schedules of the location's visible units, grouped when identical. Use a canonical location KID from GetBankLocations and reuse your manager bearer session. Requires an active manager, an assigned Tab, Location Read, Unit Read, matching site/bank/location scope and RetentionDays visibility. Opening hours never grant access.
const response = await fetch(apiBase + '/api/v1/locations/' + encodeURIComponent(locationKid) + '/opening-hours', {
headers: { Authorization: 'Bearer ' + token, 'Accept-Language': 'en-GB' }
});
if (!response.ok) throw new Error('Opening hours unavailable: ' + response.status);
const hours = await response.json();
for (const group of hours.groups) {
console.log(group.units, group.weekly, group.exceptions, group.isOpenNow, group.nextChange);
}
The response contains locationKid, timeZone, calculatedAt and groups. Each group has units:[{kid,name}], weekly, exceptions, nullable isOpenNow and nullable nextChange. Schedule rows contain label,status,opens,closes,closesNextDay,daysOfWeek,date. Stable status strings are Open, Closed, AllDay and Unknown. Only Open has HH:mm times; closesNextDay identifies midnight/overnight closing. Weekly rows use ISO weekdays 1–7 (Monday–Sunday) and null date; exception rows use a YYYY-MM-DD date and an empty weekday array. Labels/names use Accept-Language. Empty groups is valid.
Opening and closing fields independently inherit previous weekdays within the authorized Alive main terminal's plan. Child-unit opening settings and exceptions do not override it. A known controller with no weekly limits is AllDay. Missing, hidden or cyclic owners produce Unknown; never interpret null isOpenNow as closed or open. Equal explicit times mean Closed; short intervals are preserved. Priority is Custom1, Custom2, Custom3, configured holidays, first Wednesday, weekly schedule. One exception is returned per date, from today through two calendar months inclusive, across year boundaries. Leap-day exceptions apply only in leap years. Configured May 1, Constitution Day and legacy Great Prayer Day rules are supported. An explicit date exception replaces the previous day's overnight spill.
Times follow the location's TimeZoneId/legacy TimeZone, then the bank's, defaulting to Europe/Copenhagen when absent. DST gaps advance to the first valid minute; repeated times use the first opening and last closing occurrence. nextChange includes its UTC offset and is null when unknown or no transition is found within 369 days. calculatedAt is the observation time; reload when current status is needed. These are planned hours, not equipment readiness or guaranteed access. Values are read on request; avoid polling more often than once per minute and pause hidden pages.
400: invalid/wrong-site KID; 401: sign in again; 403: missing scope/Tab/read rights (reason may be missing-location-read or missing-unit-read); 404: absent or retention-hidden location; 503: unavailable, invalid or oversized data. Show 503 as unavailable, with manual retry. Up to 255 visible units; no writes. Included in client packages 0.4.2 for this beta release.
Opening hours come from the authorized main terminal identified by the same-tenant, same-bank and same-location Alive.MainId hierarchy. Opening settings are read from that terminal in Log24. Unit-level opening overrides and eState.MasterUnitId are not used for this lookup. A missing, hidden, invalid or chained main terminal yields unknown opening hours.
Missing, empty or zero opening-time values mean no configured time restriction (AllDay). An optional custom exception with both month and day unset is ignored. Invalid date exceptions are ignored. Malformed weekly hours and unresolved main-terminal mappings remain unknown.
Location reservations (unreleased)
GetLocationReservations: GET /api/v1/locations/{locationKid}/reservations?from=2026-10-19&days=7. Use the same manager bearer session. Requires Bookings1, Location/Unit Read, matching site/bank/location scope and RetentionDays visibility. User Read is also required. Each item adds userNumber and userName from the resident latest bank Log7 settings; missing values are empty strings. Denial returns 403 before reading reservation data. Each item also includes canonical userKid (null for an unknown resident). For display only, fall back to userKid when userNumber is empty; userName remains empty when unavailable.
The response has locationKid, from, days and items [{unitKid,startMinute,durationMinutes}]. StartMinute is local wall-clock minutes since 2000-01-01; durationMinutes is positive. Use the location calendar time zone for presentation, without interpreting these coordinates as UTC. Show exact intervals, including overlaps, midnight crossings and reservations outside calendar slots. Reads the tenant's current Log5 snapshot; no bank-history fallback. Cancelled and AUT/isy entries are excluded. Weekly positions below 10080 lack a concrete date and are omitted. Dates must be 2001 or later, days 1–31. Up to 5000 rows; overflow fails rather than returning partial occupancy. 400 invalid range/KID, 401 expired session, 403 denied, 404 hidden location, 503 unavailable/oversized data. Show an unavailable state on error; an empty or failed overlay is no guarantee of availability. No writes.
Location reservation calendars
GET /api/v1/locations/{locationKid}/booking-calendars, operationId GetLocationBookingCalendars (dated contract prepared for beta), reads the opening-aware calendars of visible units. Reuse the manager bearer token and a canonical location KID from GetBankLocations. Requires an active manager, Bookings1, Location Read, Unit Read, matching site/bank/location access and RetentionDays visibility. No User Read is required; no resident or reservation data is returned. All access checks precede business-data reads.
const response = await fetch(apiBase + '/api/v1/locations/' + encodeURIComponent(locationKid) + '/booking-calendars?from=2026-10-20&days=14', {
headers: { Authorization: 'Bearer ' + accessToken, 'Accept-Language': 'en-GB' }
});
if (!response.ok) throw new Error('Calendar request failed: ' + response.status);
const { groups } = await response.json();
for (const group of groups) {
if (group.status !== 'Configured') continue; // Ignore unknown future statuses.
for (const day of group.days)
for (const slot of day.slots)
console.log(day.date, slot.startMinute, slot.durationMinutes, slot.type);
}
Dated calendars (prepared for beta)
The calendar API now combines recurring turns with location opening hours, inherited settings, holidays and date exceptions. Optional query parameters: from=2026-10-20 (ISO date; default today in the location time zone), days=14 (1–31). Invalid ranges return HTTP 400. The response adds timeZone, from and days; every group day has date and dayOfWeek. Configured groups contain the requested dates, rather than a repeating seven-day template. Slots are clipped to each date and opening interval: startMinute is 0–1439, durationMinutes is positive and startMinute + durationMinutes never exceeds 1440. Type 0=reservation, 1=chance, 2=closed, 3=unknown opening hours. Unknown must never be displayed as available. Groups also distinguish effective opening schedules. Render returned dates directly; fetch another range when navigating instead of repeating days or merging opening hours in the client. This is configuration only, not occupancy or a guarantee that a reservation can be made. Portal client packages 0.24.0 include this contract. Frontend range navigation and lifecycle checks have passed; beta deployment is pending.
Configured groups have expanded days. Malformed calendars, missing/empty calendars and the legacy no-calendar sentinel are omitted; an invalid setting on one unit does not hide valid calendars on other units. Empty groups means no visible configured calendars, not unrestricted use. At most 255 units, 8192 setting rows and an eight-second settings deadline; refresh on navigation. HTTP 400: invalid/foreign KID; 401: sign in again; 403: missing tab/scope/read permission; 404: missing or retention-hidden location; 503: unavailable, ambiguous or oversized data. Do not replace an error with an empty calendar. This endpoint does not create reservations or change settings.
Invalid date exceptions (malformed or incomplete date/time values) are ignored individually. The weekly plan and other valid exceptions remain in effect, including a lower-priority valid exception on the same date. An explicit valid closed exception is preserved.
Opening hours come from the authorized main terminal identified by the same-tenant, same-bank and same-location Alive.MainId hierarchy. Opening settings are read from that terminal in Log24. Unit-level opening overrides and eState.MasterUnitId are not used for this lookup. A missing, hidden, invalid or chained main terminal yields unknown opening hours.
Location reservation rules
GET /api/v1/locations/{locationKid}/booking-rules, operationId GetLocationBookingRules, reads configured rules for visible units. Reuse the manager bearer session and a canonical location KID from GetBankLocations. Requires an active manager, an assigned Tab, Location Read, Unit Read, matching site/bank/location scope and RetentionDays visibility. Rules do not grant access.
const response = await fetch(apiBase + '/api/v1/locations/' + encodeURIComponent(locationKid) + '/booking-rules', {
headers: { Authorization: 'Bearer ' + token, 'Accept-Language': 'en-GB' }
});
if (!response.ok) throw new Error('Reservation rules unavailable: ' + response.status);
const policy = await response.json();
for (const group of policy.groups) {
console.log(group.name, group.units);
for (const rule of group.rules) console.log(rule.code, rule.text, rule.warning);
}
The groups array is the compact layout calculated by the API. Each section contains name, units, rules, common and optional localized help. Identical rules are combined. A common section contains shared rules, followed by sections with differences. Render sections in order, using unit names when name is null. Quotas remain separate for each reservation group. There is no separate displayGroups field. All text is plain text.
Response: locationKid, calculatedAt (UTC), groups:[{name,units,rules}]. Each group has nullable configured name, units:[{kid,name}] and rules:[{code,text,warning}]. Unit KIDs are canonical and authorized. Names/text follow Accept-Language; render as plain text, never HTML. Stable codes: Method, ReservationLimit, BookingHorizon, ReservationPrice, NoShowRelease, NoShowFee, BeforeStart, EarlyRelease, CurrentTurn, OutsideTurns, Dependency, DryingRoom, SettingsConflict, InvalidCalendar, UnknownSettings. Display the text and warning flag for future codes too.
For optional value emphasis, each rule also provides parts:[{text,isValue}]. Concatenate the ordered text parts without adding separators to reproduce rule.text. Values such as counts, amounts and minutes have isValue:true; other text has false. Placement follows the selected language, including repeated values. The API sends no HTML or Markdown formatting. All parts are plain text, including stored names that happen to contain markup-like characters. Existing text, code and warning fields remain unchanged; older clients may ignore parts. If parts is absent or empty, render text. Example in English:
{
"code": "NoShowRelease",
"text": "If the resident does not arrive, the reservation is released 30 minutes after the slot starts.",
"warning": false,
"parts": [
{ "text": "If the resident does not arrive, the reservation is released ", "isValue": false },
{ "text": "30", "isValue": true },
{ "text": " minutes after the slot starts.", "isValue": false }
]
}
Web clients can create their own emphasis elements using textContent. Never use innerHTML for either representation:
for (const part of rule.parts?.length ? rule.parts : [{ text: rule.text, isValue: false }]) {
const node = document.createElement(part.isValue ? 'strong' : 'span');
node.textContent = part.text;
row.append(node);
}
For optional value emphasis, each rule also provides parts:[{text,isValue}]. Concatenate the ordered text parts without adding separators to reproduce rule.text. Values such as counts, amounts and minutes have isValue:true; other text has false. Placement follows the selected language, including repeated values. The API sends no HTML or Markdown formatting. All parts are plain text, including stored names that happen to contain markup-like characters. Existing text, code and warning fields remain unchanged; older clients may ignore parts. If parts is absent or empty, render text. Example in English:
{
"code": "NoShowRelease",
"text": "If the resident does not arrive, the reservation is released 30 minutes after the slot starts.",
"warning": false,
"parts": [
{ "text": "If the resident does not arrive, the reservation is released ", "isValue": false },
{ "text": "30", "isValue": true },
{ "text": " minutes after the slot starts.", "isValue": false }
]
}
Web clients can create their own emphasis elements using textContent. Never use innerHTML for either representation:
for (const part of rule.parts?.length ? rule.parts : [{ text: rule.text, isValue: false }]) {
const node = document.createElement(part.isValue ? 'strong' : 'span');
node.textContent = part.text;
row.append(node);
}
Only identical calendars and complete rule settings are grouped. SettingsConflict means one calendar contains different policies; separate display groups do not create independent quotas. Counts describe upcoming reservations per resident, within the calendar group or globally. Positive week limits include the current calendar week; zero uses the legacy 400-day horizon. Missing before/after/add-time settings default to 15 minutes; drying-room search defaults to 4320 minutes. Malformed values produce warnings instead of permissive claims. V3 calendars are supported; absent calendars are omitted except instant reservations. Empty groups is valid.
Currency comes from registered unit, visible controller, location or bank settings, never the UI language. Unknown currency is explicitly labelled with warning=true. Hidden dependency names are not returned. This configuration snapshot is not live equipment readiness, remaining resident quota or a booking validation result. No resident bookings are loaded and nothing is written. Refresh on navigation; do not poll more than once per minute.
400: invalid/wrong-site KID; 401: sign in again; 403: missing scope/Tab/read permission; 404: absent or retention-hidden location; 503: busy, unavailable, invalid or oversized storage. Show 503 as unavailable with manual retry, never unrestricted booking. Bounded to 255 visible units, 8192 Log24 values, an eight-second settings deadline and two concurrent settings reads. Included in client packages 0.4.2 for this beta release.
Workspace terminal hierarchy
terminal.kid is a canonical Controller KID with MainId and zero UnitId, distinct from the first unit's KID. The workspace hierarchy is bank → location → controller → unit; the first unit remains a separate child. GetControllerOverview — GET /api/v1/controllers/{controllerKid} and GetControllerGroup — GET /api/v1/controllers/{controllerKid}/groups/{kind}/Core reuse GetUnitOverview/GetUnitGroup authorization and retention checks, with no extra privileges. Controller data uses the first unit's Log24 storage. Responses retain that storage unit in unit.kid and identify the controller in unit.terminal.kid. Both group lists temporarily contain Core; settings use existing type metadata, while states are empty until Core state metadata exists. Do not infer state fields. Use the returned unit KID and existing revision checks for authorized setting edits/history. Invalid controller KIDs return 400; unauthorized access 401/403; unknown or hidden controllers/groups 404; unavailable storage 503. Reuse your manager bearer token:
Units returned by GetLocationUnits, GetUnitOverview, GetUnitGroup, GetUnits and GetTerminals include nullable terminal: {kid,name,iconKid}. Use the canonical terminal KID to group a child beneath its main terminal and that terminal beneath the location. Its name uses the main unit’s reported eState.ComputerName, exactly like GetTerminals, with no fallback to eSetting.Name (empty when absent), and its opaque icon KID includes the main unit number; use iconKid unchanged with GetIconFromSet.
The API reads only bounded, trusted-tenant Alive.MainId relationships after the existing manager, Tab, operation, resource and retention checks. The main terminal must be an authorized, RetentionDays-visible Log24 unit at the same bank/location. A child's positive MainId can identify it when its own Alive row is absent. An existing parent mapping to another main unit or an invalid value is rejected. No extra rights are granted and no identifiers are inferred from names, icons or Offline.
Missing, invalid, orphan, hidden, chained or unavailable hierarchy returns terminal:null. Show an unknown-terminal group in that case; do not guess that the unit is its own terminal. Optional hierarchy failure does not discard an otherwise available overview, group or directory page. Existing HTTP errors and polling limits apply. Main and child units remain in GetUnits; GetTerminals classification and paging are unchanged. Implemented locally, unreleased; packaged clients are refreshed at beta release.
On Nortec, the line-set check under-icon is rendered in the tenant green (#4AC337). The main icon color and offline cross are unchanged; tenant selection comes from trusted site configuration.
Unit progress
Each unit returned by GetLocationUnits, GetUnitOverview and GetUnitGroup includes progress: {status, percent, remainingSeconds, calculatedAtUtc}. The API calculates this read-only estimate from the same bounded Log24 snapshot; no additional permission or endpoint is needed. Existing manager, Tab, Location Read, Unit Read, resource scope and retention checks still apply. Poll at most every ten seconds and pause hidden pages.
const response = await fetch(apiBase + '/api/v1/units/' + encodeURIComponent(unitKid), {
headers: { Authorization: 'Bearer ' + token }
});
if (!response.ok) throw new Error('Unit request failed: ' + response.status);
const { unit } = await response.json();
const progress = unit.progress;
const percent = progress?.percent; // null means unknown/inapplicable, never zero
Progress uses only clamp((now - Started) / (Done - Started) * 100, 0, 100), rounded down to an integer. Valid times return Estimated, including 100 at and after the expected end, and remainingSeconds never falls below zero. Cycle, Enabled, OutOfOrder, Connected and sequence identifiers do not affect this calculation. Missing, nonpositive or unsupported timestamps and Done not after Started return UnknownEndTime with null percent and remainingSeconds.
Values are calculated at request time from cached inputs; calculatedAtUtc does not confirm fresh device contact. The percentage measures elapsed expected time, not physical completion. Handle 401 by signing in, 403/404 as unavailable, and 503 with a later retry.
Lazy unit icons and offline status
GET /api/v1/units/icons?kid={unitKid}&kid={anotherUnitKid}, operationId GetUnitIcons, accepts 1–32 canonical unit KIDs from this site. Fetch only visible icons, deduplicate and batch requests. Requires an active manager, an assigned Tab, Location Read, Unit Read, matching bank/location scope and retention-visible units and locations. Every lookup reapplies these checks before Alive is read.
const query = new URLSearchParams();
visibleUnitKids.forEach(kid => query.append('kid', kid));
const response = await fetch(apiBase + '/api/v1/units/icons?' + query, {
headers: { Authorization: 'Bearer ' + token }
});
if (response.status === 401) throw new Error('Sign in again');
if (!response.ok) throw new Error('Unit icon lookup failed');
const { items } = await response.json();
// For status === 200, use iconKid unchanged in /api/v1/icon/{iconSet}/{kid}.svg.
Each item contains kid, iconKid, offline and status. Exactly Alive.Offline = 1 adds eIcon.close as Kid.Icons[1]; the API retains the primary icon, unit number and other presentation fields. Alive.Offline = 0 sets Kid.Icons[1] to eIcon.check, replacing any offline decoration. A missing Alive row, null or other Offline value yields offline: null and no status decoration. No MainId inference or Cycle heuristic is used.
400 rejects malformed, foreign or oversized input; 401 requires login. Per-item 403 means missing access, 404 means absent/retention-hidden, and 503 means unavailable; these items have null iconKid/offline and must not be interpreted as online. On transient failure retain the last confirmed image and retry later. Reads are bounded to the exact tenant/bank/location and cached for up to 10 seconds; HTTP responses are no-store. Refresh at most once per 10 seconds while visible, pause hidden pages and prevent overlapping requests. The public image endpoint remains anonymous and performs no Alive lookup. This adds no writes or hardware commands.
Bank icons and combined unit status
GET /api/v1/banks/icons?kid={bankKid} · operationId GetBankIcons. Accepts 1–8 canonical bank KIDs from this site; repeat kid. Requires an active manager, assigned Tab, Bank Read, Location Read, Unit Read and matching scope. Location-only grants include only those locations. Disabled locations require all-bank access; location and unit RetentionDays visibility both apply.
Any included unit with Alive.Offline=1 gives eIcon.close as the second Kid.Icons item. A nonempty set entirely known Offline=0 gives eIcon.check. Empty/incomplete data gives offline=null without added status, unless a unit is confirmed offline. Orphan Alive rows are excluded. Use opaque iconKid unchanged in the icon URL; GetIconPresentation adds count/colour while preserving status.
400: invalid/foreign/oversized input. 401: sign in again. 503: session storage unavailable. Per-item 403 means missing access; 503 means unavailable/ambiguous/oversized data, with null iconKid/offline. Failure never means online. Fetch visible banks only, deduplicate, refresh at most every ten seconds and pause hidden pages. Status cache: ten seconds per authorized location set; labels/locations: sixty seconds. HTTP no-store. Read-only Log24/Alive; up to 65,536 units per bank and 128 locations per SQL batch. Authorization is reapplied on every call.
Location icons and combined unit status
GET /api/v1/locations/icons?kid={locationKid}&kid={anotherLocationKid}, operationId GetLocationIcons, accepts 1–32 canonical location KIDs from this site. Requires an active manager, an assigned Tab, Location Read, Unit Read, matching bank/location scope and RetentionDays visibility, exactly as GetLocationUnits. Authorization precedes every status lookup.
const query = new URLSearchParams();
[...new Set(visibleLocationKids)].slice(0, 32).forEach(kid => query.append('kid', kid));
const response = await fetch(apiBase + '/api/v1/locations/icons?' + query, {
headers: { Authorization: 'Bearer ' + token }
});
if (response.status === 401) throw new Error('Sign in again');
if (!response.ok) throw new Error('Location icon lookup failed');
const { items } = await response.json();
// For status === 200, use iconKid unchanged in /api/v1/icon/{iconSet}/{kid}.svg.
Each item has kid, iconKid, nullable offline and status. Any unit in the authorized overview with Alive.Offline=1 gives offline:true and eIcon.close in Kid.Icons[1]. Only a nonempty set where every unit has Alive.Offline=0 gives offline:false and eIcon.check. Otherwise status is null, with no added status icon. A known offline unit takes precedence over missing data. Empty locations, missing/invalid Alive values, hidden units and orphan Alive rows never establish online status. Only units returned by GetLocationUnits contribute. The primary location icon and LocationId text are preserved.
400 rejects malformed/foreign KIDs or invalid batch size; 401 requires login. Per-item 403 means denied access, 404 means absent or retention-hidden, and 503 means temporarily unavailable, with null iconKid/offline. A failure never means online. Retain the last confirmed image on transient failures. Read visible icons only, batch duplicates, pause hidden pages and refresh at most every 10 seconds without overlapping requests. Location and unit lookups share the bounded Alive cache for up to 10 seconds. Responses are no-store; unchanged image URLs can be reused without resetting the image. No database writes or hardware commands; public image rendering does not query Alive.
Unit type and groups
GetLocationUnits now includes unitType (number), unitTypeName (eUnitType name when defined) and unitTypeSource. Log24 supplies the type in the same query as the other columns.
GET /api/v1/units/{unitKid}, operationId GetUnitOverview, returns {location,unit,descriptorAvailable,settingGroups,stateGroups}. Use a canonical unit KID from the location list. Requires an active manager, at least one Tab, explicit Location Read and Unit Read, and matching site/bank/location access. Both unit and location must be visible within RetentionDays.
Only the original packed UnitType determines type, decoded with the eight-bit (value >> 1) & 255 rule. UnitType2 is ignored, including as a fallback. Missing/invalid types are null, never an invented Type000; unknown numeric types are retained.
Groups come from the release’s Catalog.json catalog: distinct eSettingGroup/eStateGroup names ordered by numeric value. Missing or unsupported types give descriptorAvailable=false and empty groups. These are metadata only, without setting/state values, editing rights or hardware access.
Unit data is cached for up to 10 seconds; location labels and manager snapshots for up to 60 seconds. Authorization is checked on every request. Accept-Language localizes names/cycle labels, not group identifiers. Poll at most every 10 seconds and pause hidden pages.
400: invalid/foreign KID; 401: sign in again; 403: missing Tab/scope/read access; 404: missing or retention-hidden unit/location; 503: retry later. After scope checks, 403 may have reason missing-location-read or missing-unit-read.
The portal uses this operation at /units/{unitKid}. Clicking a unit row adds its shortcut under the location in the workspace and shows its type's groups. Removing the shortcut never deletes the unit.
Read a unit group's settings or states
GET /api/v1/units/{unitKid}/groups/{kind}/{group}, operationId GetUnitGroup. Set kind to settings or states, and use an exact group identifier from GetUnitOverview. Returns {location,unit,kind,group,items:[{name,valueType,scope,valueStatus,value,ms2000}]}. The API determines the fields from the unit type. The same active-manager, Tab, Location Read, Unit Read, site/resource and RetentionDays checks apply before reading any values.
const response = await fetch(`${api}/api/v1/units/${encodeURIComponent(unitKid)}/groups/states/Widget`, {
headers: { Authorization: `Bearer ${token}`, "Accept-Language": "en-GB" }
});
if (!response.ok) throw new Error(`Group request failed: ${response.status}`);
const page = await response.json();
for (const field of page.items) console.log(field.name, field.valueStatus, field.value);
One bounded Log24 read returns the newest MS2000 per declared current-unit field. Missing rows have valueStatus=missing; stored null/empty strings remain stored. No catalog default or older value is substituted. MainUnit and other-object bindings have status other-scope and no value; their owning KID is not inferred. Hidden settings are omitted and credential settings are redacted without reading their values. Fields and groups retain stable enum names. This operation is read-only; no hardware commands or edits.
Values are uncached; type/location/manager snapshots retain the existing 10/60-second limits. At most 512 fields and 16,384 characters per value; ambiguous/oversized data fails the whole request with 503. Poll settings no faster than every 5 seconds and states every 10 seconds and pause hidden pages. 400: invalid kind, syntax or KID/site; 401: sign in again; 403: missing permissions; 404: invisible unit/location or group not declared for the current type; 503: try later. After scope checks, 403 may include missing-location-read or missing-unit-read. The portal lazily opens the group and stores its shortcut below the unit in the workspace; removing it never changes device data.
Price settings marked with AttributeMetaRegEx(RegExs.Price) include valueFormat: "Price" and pattern in GetUnitGroup (also GetControllerGroup). GetUnitSettingHistory returns the same valueFormat at page level. These are presentation metadata; they grant no write access. For Price, display raw value / 100 with two decimal places, and convert edited amounts back with exact decimal arithmetic (12.50 → "1250"). Apply pattern (the .NET RegExs.Price) and integer minimum/maximum to the raw value after conversion, never to displayed text. The current Price pattern accepts 1–6 digits, so raw 0–999999 represents 0.00–9999.99. SetUnitSetting still accepts and returns raw invariant text, and validates it on the server; sending "12.50" returns 400. Empty optional values stay empty. History values and restore requests stay raw; do not scale history twice. Unknown/null formats use the ordinary editor. No currency is inferred from this format. This addition is unreleased.
Live sync and setting history
hasHistory is true when the setting has at least one bank Log2 history record. Show the history control only when both canReadHistory and hasHistory are true; the flag does not grant permissions. History is still fetched on demand.
GetUnitGroup adds sync, changedBy:{kid,kind,name,iconKid} and canReadHistory for settings. Sync comes from the exact bank Log2 record matching the displayed value: only 1 is acknowledged; other values are pending, and null means unknown. A sync-only change does not change MS2000 or invalidate the value revision. Poll settings at most every five seconds (states every ten), with no overlap and a pause on hidden pages.
GetUnitSettingHistory uses the same active manager, assigned Tab, location scope, Location Read, Unit Read and RetentionDays checks. Audit labels grant no access to the editor's account or directory. Only declared current-unit settings are eligible; hidden, credential and other-scope fields are excluded.
The response is {unitKid,group,setting,items:[{value,ms2000,sync,changedBy}],nextBeforeMs2000}, newest first. Request the next page with &beforeMs2000=NEXT_CURSOR; null means the end. Limit is 1–50, default 25. Open history on demand; do not poll one history request per row. Names/icons are current Log7 labels, not historical snapshots. Manager/service labels use bank zero, installers the tenant bank and residents the unit's bank; unknown identities can have no KID/name. changedBy is null when no editor is recorded (UserId zero); display no user icon or name in that case. Unknown nonzero identities remain present.
400: invalid input/site; 401: sign in again; 403: missing read access; 404: unavailable unit/group/setting; 503: storage failure or ambiguous/oversized values. No automatic retry loop. Each call has an eight-second storage deadline and a 16,384-character value limit. No database writes, count query or history cache.
Edit a unit setting
SetUnitSetting: POST /api/v1/units/{unitKid}/groups/settings/{group}/{setting}. GetUnitGroup now also returns canEdit, revision, required, minimum, maximum and selectable options. Editing requires Unit Write as well as the read operation's account, Tab, scope and retention permissions. The API rechecks the current manager and unit type inside the write transaction.
Send invariant text in value, up to 4096 characters, and the field's expectedRevision. Type, required, range, pattern and selectable-option rules come from the enum metadata and Catalog.json. Booleans normalize to 0/1. No defaults are inserted. States are always read-only. Hidden, device-owned, read-only, ORM-managed and credential settings are not editable. MainUnit/other-object bindings and dynamic option sources remain unsupported for editing.
const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
const path = `${api}/api/v1/units/${encodeURIComponent(unitKid)}/groups/settings/Core`;
const read = await fetch(path, { headers });
if (!read.ok) throw new Error(`HTTP ${read.status}`);
const field = (await read.json()).items.find(item => item.name === "Name");
if (!field?.canEdit) throw new Error("This setting cannot be edited");
const saved = await fetch(`${path}/Name`, {
method: "POST", headers,
body: JSON.stringify({ value: "Washer 1", expectedRevision: field.revision })
});
if (!saved.ok) throw new Error(`HTTP ${saved.status}; reload before retrying`);
const confirmed = await saved.json(); // value, ms2000, revision
A successful response confirms storage, not delivery to the device: it returns the canonical unit KID, group, setting, value, MS2000 and new revision. The change is appended to bank Log2 with Sync=0 and the editor's UserId; the current Log24 projection is verified before commit. 400: invalid value; 401: sign in again; 403: write denied; 404: unit/group/field unavailable; 409: value or type changed; 503: storage failure. After a conflict or lost response, read back before editing again. Never automatically replay a write.
In the portal, clicking one setting group adds all that unit's setting groups to the workspace. Clicking a state group adds all state groups. Settings save on blur and selections save immediately; the confirmed value is shown only after API success. Polling pauses during editing, saving or an unresolved error.
Manager language
Authenticated responses use the manager's saved Language preference, overriding Accept-Language and tenant defaults. All operational manager languages are supported. In automatic mode, Washco uses en-GB; other tenants follow Accept-Language with en-GB as fallback. Quality preferences are honored and q=0 excluded. Content-Language reports the result. Known name placeholders, including names in GetUnitDocuments, resolve after reading raw data; unknown IDs and surrounding text are preserved. The existing manager snapshot cache applies (up to one minute); a changed language requires no new token. Anonymous widgets keep their public language policy. The example passes the language from authenticated responses to widgets without sending them a bearer token.
GetLocationUnits now returns cycle (stable eCycle name) and cycleText (Accept-Language) per unit. Both are null for missing/invalid values. The newest MS2000 from eSetting.Cycle (1619, Settings) and eState.Cycle (20, States) wins; States wins ties. An invalid newest value never falls back to an older value. Unit data is now cached for at most 10 seconds; location labels and manager permissions for up to one minute. Both SQL branches are bank/location scoped. The portal refreshes every 10 seconds, pauses in hidden tabs, prevents overlapping requests and hides stale details on failure. External clients can repeat this GET with the same bearer token and Accept-Language every 10 seconds.
Settlement: viewing, history and downloads
Every call requires Authorization: Bearer TOKEN, the Settlement2 Tab, Bank Read, User Read and access to the entire bank. Location-only access cannot expose bank-wide settlement data. Permissions are checked on every request with a manager snapshot cached for at most one minute. These GET operations never close, undo or modify a settlement.
Omit beforePeriod initially. History returns up to 25 closed periods, nextSettlement and nextBeforePeriod. Pass the next cursor unchanged; null means the end. Unknown dates and values are null. Dates use UTC. Period 0 is the provisional current period, available through details and downloads; it can change until settlement.
Details contain sourceEntries, includedEntries, groups and formats. Each group has group, currency, entries and amountMinor. Amounts are signed database values in minor units, not formatted currency amounts. Different currencies are never added together. Stored history totals may differ from export totals.
ChargePoint_58/TimeNew power consumption is excluded; cash banks also exclude Month and Transfer. Group priority is ETest, EInstaller, EGuest, configured number masks (U), EDate, then LR. Masks use % for multiple characters and _ for one character. Valid legacy entries classified as Unknown retain their recorded amounts. Current user numbers, names, tags and attributes are used, so regenerating a historical file may differ from its original version. Settlement is exempt from RetentionDays: deleted users remain included in period details and downloads regardless of deletion age. Normal manager, Tab, bank and read permissions are still enforced.
The ZIP contains one file per group and currency plus a reconciliation manifest.json. Empty periods contain only the manifest. Text formats may omit groups with no exportable amounts; group totals remain in the manifest. XLS produces real .xlsx workbooks with Number, Amount and UserId following the export convention; UserId in this compatibility file is numeric, while HTTP object identifiers are KIDs. Other formats use UTF-8 text with CRLF. Excel keeps the database amount sign; NAVISION, for example, reverses it.
Formats: XLS, ATB, BL, DEAS, FRUEHØJGAARD, HEIMSTADEN, LEJERBO, MD90_1, MD90_3, MD90_3_minus, MD90_3_plus, MD90_3_AABKBH and NAVISION. MD90_3 is defined for banks 1001 and 1068 only. NIRAS and ROBERT are obsolete. HUMAN, KMD, LYKKEBO and MD90 are not offered because the reviewed shared code contains no implemented export for them. Format identifiers are case-sensitive; use the list returned in the details.
const headers = { Authorization: `Bearer ${token}` };
const base = `/api/v1/banks/${encodeURIComponent(bankKid)}/settlements`;
const details = await fetch(`${base}/12`, { headers });
if (!details.ok) throw new Error(`HTTP ${details.status}`);
const period = await details.json();
const download = await fetch(`${base}/12/download?format=XLS`, { headers });
if (!download.ok) throw new Error(`HTTP ${download.status}`);
const url = URL.createObjectURL(await download.blob());
const link = document.createElement('a');
link.href = url; link.download = 'settlement-12.zip'; link.click();
setTimeout(() => URL.revokeObjectURL(url), 60000);
This example assumes the same origin. External browser portals use the full API base address and an allowed CORS origin. 400 means invalid KID/period/format, 401 requires login, 403 means denied permissions, 404 means an unknown closed period, 422 means data cannot be exported safely, and 503 means temporarily unavailable data. Causes of 422 include invalid transaction codes, invalid numbers/currency, duplicate export numbers across users, field width overflow or more than 100,000 entries/10,000 users. No partial files are returned. Correct data/format instead of retrying 422. Back off before retrying 503.
History and period sources are cached for at most one minute, coalescing concurrent reads. Details load only when a period is selected. No background database reads or MySQL writes occur. Legacy readiness calculations and automatic jobs have not been migrated; this API does not claim a bank is ready to close.
The additional heatmap array contains {latitude, longitude, amount} for all qualifying purchases retained in Log1Hour, grouped by coordinates. There is no row limit or additional timestamp filter: the database maintains the recent-hour table. Missing/invalid coordinates are omitted; existing purchase and transfer filters remain. Amount is summed in major currency units, without currency conversion. Only animated items are limited to the newest purchases. The portal replaces the entire heatmap immediately on every ten-second refresh, independently of coin animation. No names or user identifiers are included.
Map1: Public purchase map
GET /api/v1/public/displays/Map1 · operation GetPublicDisp73 in the Public Swagger definition. No login is required. The server selects the tenant; query parameters cannot change tenant, bank or time boundary. ?limit=100 is optional (default 100), accepts 1–200 and returns HTTP 400 for invalid values. The limit applies only to animated items; heatmap data is complete. All limits share one cached snapshot; only animated items are sliced to the requested limit.
Use /api/v1/public/displays/Map1. The old disp73 path has been removed and returns 404. The operation ID remains GetPublicDisp73 (JavaScript: getMap1()).
const response = await fetch('https://api.team.kombine.technology/api/v1/public/displays/Map1');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const sample = await response.json();
for (const p of sample.items) {
// Ignore known p.kid. Spread new coins evenly across the next 10 seconds.
queueCoin(p.kid, p.latitude, p.longitude, p.timestampUtc, p.amount);
}
The response is {measuredAtUtc, refreshAfterSeconds: 10, items: [...]}. refreshAfterSeconds is always 10. The items array contains {kid, latitude, longitude, timestampUtc, amount}, newest first. The items array selects at most the latest 200 purchases from the maintained Log1Hour table without a timestamp filter. Missing/invalid coordinates omit a row, so fewer may be returned. Transfers and rows whose Text ends in E are excluded.
timestampUtc is ISO 8601 UTC: 2000-01-01T00:00:00Z + original MS2000 (without an offset). kid is the canonical transaction KID containing original time and tenant/bank/location/unit; it grants no permissions. User IDs, names, tags and transaction text are omitted. Amount is positive major units (minus Amount / 100), without currency conversion or a currency field.
Fetch every 10 seconds without overlapping requests. Ignore existing KIDs, merge with retained events and remove the oldest above 100. New coins are spread evenly across the next ten seconds, each falling once; timestampUtc is only used for ordering and removing the oldest events. Hidden tabs suspend requests/animation and resume on return. Reduced-motion settings disable falling animation. The API shares a ten-second cache. An empty array means no displayable events. HTTP 503 means unavailable data: keep existing coins and wait 30 seconds (Retry-After). External browser clients need an allowed CORS origin. Public display KIDs do not authorize protected bank operations.
Users2 uses Log tables exclusively for business data. Resident IDs, number uniqueness, tag ownership and changes use Log7; synchronization is requested through Log2. Obsolete Users and Settings tables are neither read nor written. API routes and commands are unchanged.
Users2: resident editing and export
GetBankUsers supports locationKid and deleted=all|active|deleted|no-access. Locations must belong to the same bank and the manager's grants. no-access selects visible residents without recorded Access in any location the manager may see. Empty location lists and NoAccess-only lists match. Bank-wide access evaluates the entire bank; hidden locations do not affect the result for location-restricted managers. Residents without an association to a permitted location remain hidden from those managers. Retention still applies, so visible deleted residents may match. A selected locationKid additionally requires an association to that location. Filtering precedes paging and also applies to CSV export. Keep these filters with cursors; restart without a cursor when changing them. Unknown filter values return 400, missing permissions 403, and unavailable data 503.
const page = await client.getBankUsers(bankKid, {
sort: 'number', deleted: 'no-access', pageSize: 25
});
// For the next page, retain these options and add cursor: page.nextCursor.
GET /api/v1/banks/{bankKid}/users/{userKid}/workspace (GetBankUserWorkspace) returns authoritative edit fields and an opaque revision. Requires Users2, User Read and bank-wide/tenant-wide access. Location-only managers can still read their list and export, but cannot edit shared residents through these operations.
POST /api/v1/banks/{bankKid}/users (CreateBankUser) accepts {"action":"create","name":"New resident","number":"001"} and returns HTTP 201 with the resident KID. Requires User Create. Assign tags and location access separately.
POST /api/v1/banks/{bankKid}/users/{userKid}/commands (ExecuteBankUserCommand) requires the current revision. All commands require User Read. Attributes require Write; tag/location require Create; delete/restore require Delete; replace requires both Create and Delete. Profile requires Rename for a changed name and RenameExtrenatId for a changed number. All require Users2 and bank-wide scope. Manager identity and tenant come only from the session and trusted site configuration.
// baseUrl and token from the login example; bankKid/userKid are KIDs returned by the API.
const path = baseUrl + '/api/v1/banks/' + encodeURIComponent(bankKid) + '/users/' + encodeURIComponent(userKid);
const headers = { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' };
const read = await fetch(path + '/workspace', { headers });
if (!read.ok) throw new Error('HTTP ' + read.status);
const current = await read.json();
const saved = await fetch(path + '/commands', { method: 'POST', headers,
body: JSON.stringify({ action: 'profile', revision: current.revision, name: 'Updated name', number: current.number }) });
if (saved.status === 409) throw new Error('Reload and review current details before retrying');
if (!saved.ok) throw new Error('HTTP ' + saved.status);
const updated = await saved.json();
Resident icons: GetBankUserWorkspace and command responses include iconKid, availableIcons and canEditIcon. To change an icon, call ExecuteBankUserCommand with action: "icon", the current revision and an exact eIcon name with eIconSubject.Person metadata. This requires Users2, User Read, User Write and a bank-wide grant. A current non-Person icon appears first for display only; do not submit it as a new choice. Icons are served locally through /api/v1/icon/g/{kid}.svg.
{"action":"icon","revision":"<revision from GetBankUserWorkspace>","icon":"user"}
Icon changes do not require or change the resident's name or number. Only display the returned icon and use the new revision after HTTP 200; serialize edits that share the revision. Invalid icons return 400, missing permission 403, stale revisions or deleted residents 409, and storage failures 503. After 409 or an uncertain network outcome, reload the workspace and review it before retrying. No-op clicks on the selected icon should not send a write.
profile: name and number. Checks number format and existing active numbers.
attributes: the complete attributes list with canonical eUserAttribute names and value (-1 means no numeric value).
tag: tagKid and state (Unlocked, Locked or Deleted). The canonical KID must belong to this bank. A tag owned by another resident is rejected; historical tags cannot be modified.
location: locationKid and state (Access or NoAccess). The location must be active.
delete: optional deleteAtUtc. Empty/past means now and deactivates tags. Future deletion can be scheduled up to 366 days ahead.
restore: restore a resident or cancel scheduled deletion. Deleted tags are not automatically reactivated. Retention limits restoration.
replace: name, number and optional deleteAtUtc. Deleting the old resident and creating the new one share one transaction. Balance, tags and location access are not transferred. Future deletion does not release the old number yet.
HTTP 400: invalid fields/KID/number format. 401: invalid session. 403: insufficient rights. 404: unavailable within retention. 409: revision conflict, duplicate number or tag in use. 503: write connection/storage unavailable. ProblemDetails includes a stable code when possible, such as conflict, number-exists, tag-in-use or writes-unavailable. After a network failure on POST, read back and check the result before retrying; do not assume rollback.
GET /api/v1/banks/{bankKid}/users/export (ExportBankUsers) returns UTF-8 CSV with semicolons and stable column identifiers. Same filter/sort/direction/locationKid/deleted and rights as the list. Maximum 10,000 residents and 4 MiB text; HTTP 422 requires narrower filters and never returns a partial file. Each page rechecks authorization; this is not a transactionally frozen snapshot. CSV does not contain activation codes or balances.
GET /api/v1/banks/{bankKid}/users/{userKid}/activation (GetBankUserActivation) returns activation-letter data including activationCode. Requires bank-wide User Create; deleted residents are rejected. Treat the code as a credential: do not log or cache it.
qrCodeDataV1 is the complete QR payload, not an image. It preserves FlexORM's GetQRCodeString() format: the tenant URL, #, and a FlexCipherLongs fragment containing the bank code, user code and UTC seconds since 2000-01-01. Render the string unchanged with your own QR library (including a quiet zone); never send activation credentials to an external QR service. An empty string means the tenant has no activation URL. Reload the endpoint for a fresh timestamp; validity is determined by the existing activation consumer. Requires an active manager, Users2, User Read, User Create and a bank-wide grant. Invalid KIDs return 400, invalid sessions 401, insufficient permissions 403, missing/deleted residents 404 and unavailable storage 503. The response is not cacheable.
QR version 2:qrCodeDataV2 encodes five FlexCipherLongs values in order: bankCode, userCode, seconds, noise, checksum. The first three match version 1 in the same response. Noise is freshly generated using a cryptographic random generator for each payload, uniformly from 0–1073741823 (30 bits); repeats are possible. Checksum is (((bankCode * 31 + userCode) * 31 + seconds) * 31 + noise) % 1073741824. For overflow-safe calculation, start with c = bankCode % M, then apply c = (c * 31 + value % M) % M for userCode, seconds and noise, with M = 1073741824 and UInt64 intermediates. Decode using FlexCipherLongs.Parse(5, fragment), validate the parse, check both noise and checksum are at most 1073741823, and verify the fifth value against the calculation. These are logical 30-bit unsigned values encoded as numbers, not fixed-width byte fields. Noise does not authenticate the payload or prevent replay; checksum is error detection only. Migrate previous unreleased four-value version 2 readers and regenerate their QR codes; no fallback to older version 2 formats. Version 1 remains three values. Both fields are empty if the tenant has no activation URL. Render the payload locally without modification.
curl --fail-with-body -H "Authorization: Bearer $TOKEN" "$API/api/v1/banks/$BANK_KID/users/$USER_KID/activation"
# Render response.qrCodeDataV1 locally as a QR code; do not log the response.
Changes record the manager ID and request synchronization through the existing backend. Success confirms storage, not delivery to physical equipment. Synchronization and scheduled deletion require the existing backend. EVaskeri/CP autologin, subscription management and test/information messages have not been migrated. Local convenience login grants no additional permissions.
Reservations · Bookings1
GetBankBookings: GET /api/v1/banks/{bankKid}/bookings. Requires Bookings1 (8), Location/Unit/User Read and bank-wide or specific location grants. Location grants constrain both rows and filter options. All object identifiers are canonical KIDs belonging to the site's tenant.
For bookings, account and bank-user lists, repeat locationKids to select up to 1000 canonical location KIDs within the bank (for example, ?locationKids=KID1&locationKids=KID2). Every selected location must be authorized. Account totals, revision and export and resident counts and exports use the same selection. A resident matches an association with any selected location. Keep the selection unchanged with a cursor; restart without a cursor after changing it. The existing single locationKid remains supported. A selected unit must belong to the selected locations; incompatible filters return 400, unauthorized locations 403.
Filters: from/through are inclusive local start dates; defaults are UTC today's date minus 7 through plus 90 days, at most 367 dates. Optional locationKid, unitKid, userKid, search (resident name/number, at most 100 characters) and status=all|active|cancelled. limit is 1–200, default 50. offset is 0–100000; advance by limit while hasMore is true. Pages are not a locked snapshot; refresh after changes.
items contains the latest current event per location/unit/resident/start. Superseded Log5 rows (nonzero Period) and AUT/isy codes are excluded. startLocal/endLocal are local times without a UTC offset: never append Z. recordedAtUtc is the UTC event time. Weekly reservations instead have a weeklyMinute position 0–10079 and are always included regardless of date filters. durationMinutes is positive; cancelled expresses cancellation. source retains the system code, including ARR/ArR (attendance), FE0 (no-show) and FE1 (no-show with fee).
ExecuteBankBookingCommand: POST /api/v1/banks/{bankKid}/bookings/{bookingKid}/commands with {"action":"cancel"} or {"action":"restore"}. Use the reviewed row's KID, which also identifies its revision. Commands additionally require Unit Write and a grant for the reservation's location. canCancel/canRestore are presentation hints; the API always rechecks authorization and the current version.
const booking = page.items.find(item => item.canCancel);
if (!booking) throw new Error('No reservation on this page permits cancellation.');
const response = await fetch(`${base}/api/v1/banks/${encodeURIComponent(bankKid)}/bookings/${encodeURIComponent(booking.kid)}/commands`, {
method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ action: 'cancel' })
});
if (!response.ok) throw await response.json();
const changed = await response.json();
A command appends a Log5 event with the duration's sign reversed, Currency SER and Sync 0, retaining history. HTTP 200 confirms storage; synced=false means existing backend synchronization is pending. No direct device command is sent. 400: invalid filter/KID/action; 401: invalid session; 403: insufficient permission; 409 conflict: stale event, or time-occupied: overlapping booking; 422 weekly-restore-unavailable: unsupported weekly restoration; 503: unavailable storage/write connection. After a network failure, read the list again before considering another attempt. Never automatically retry POST.
Limitations: no creation, recurrence expansion, export or fee changes. Raw weekly positions are displayed without guessing the first weekday; restoring weekly reservations is not supported yet. An active weekly reservation conservatively blocks restoration on that unit. Restoration checks overlaps but does not recalculate controller booking rules. Writes require InnoDB and at most 20,000 current events on the unit; filters are bounded to 4,096 names. No caching or automatic polling is used.
Transactions · Account2
Each posting includes locationIconKid: a house icon with the authorized location number in Text, or null when locationKid is null. Use this opaque value unchanged in the icon image URL, like unitIconKid. The number is available immediately, independently of live status lookups. Available on alfa; beta/production promotion is pending.
Receipt grouping and FlexOrm decoding
Transaction descriptions use decoded Kombine.Flex.FlexDto.KrumbValue.TransactionLine.ToString() text, including program, duration, soap and transfer details. The API resolves numeric localization placeholders. Safely displayable text-only legacy descriptions remain supported; absent DTO text uses a safe fallback. Raw JSON and payment identifiers are not exposed. Each item additionally has documentKey (an opaque bank-scoped string), documentId (positive DocId or null), isAnonymized (boolean) and paymentKind (Credit, ReserveRefund, Managed, or an empty string). Never parse the display description to identify a payment operation; use paymentKind as metadata.
documents is an additional array of {key, docId, lines, totals} covering this page only. Lines group by DocId within the same original resident, location and period, across units. Invalid/missing DocId and payment-managed lines stay separate. Documents sort by their earliest loaded line, newest document first; lines sort chronologically. Document totals cover its loaded lines, separately by currency. A filter or page boundary may cut a receipt: these are not complete invoice totals. Flat items, offset/limit, hasMore and full-selection totals keep their existing meaning. Merge further pages by documentKey, deduplicate by posting kid and require equal revisions; never fetch outside the authorized filters to complete a document.
for (const document of page.documents) {
console.log(document.key, document.docId, document.totals);
for (const line of document.lines) console.log(line.kid, line.description);
}
Retention and payment-managed entries
Tenant Log24 LawAccountingYears applies to all entries; LawSurveillanceDays also applies to zero-amount entries. A positive manager Log7 value overrides the corresponding tenant setting; a year is 365 days. Missing, invalid or zero values mean no identity retention. Entries older than either applicable cutoff are returned in bank/location/unit views with the bank's GDPR user KID (UserId 1000), empty userName/userNumber, a safe transaction-type description, isAnonymized=true and canReverse=false. Their amounts remain in totals. With an explicit userKid, expired entries are excluded before pagination and totals. The same rules apply to CSV/XLSX; their existing column layout is preserved.
Revision checks include retention visibility and are cached separately for each authenticated manager; the same manager's identical authorized selection still shares a maximum 30-second cache. There is no client-supplied manager override. Managed payment entries retain their safe display description and expose paymentKind as metadata; ordinary reversal is unavailable even if the stored transaction type resembles consumption. Reversal also rechecks retention in its write transaction. These ineligible requests return 422 reversal-unavailable. Existing 400/401/403/409/503 handling remains applicable. Do not automatically retry an uncertain financial write.
This ports the listing behavior without a FlexOrm runtime dependency, legacy business tables, external payment refund calls or payment-metadata lookups outside Log. Generated clients and downloadable packages are synchronized in version 0.4.2.
GetBankAccount: GET /api/v1/banks/{bankKid}/account. Requires Account2 (2), Bank/Location/Unit/User Read and a bank or location grant. The current manager account, credential stamp and site's tenant are checked before any business read. Location grants constrain rows, totals and filter options. Reuse the ordinary manager bearer session.
from is inclusive in timeZone and defaults to today in Europe/Copenhagen, respecting daylight-saving transitions. Omit through for no upper date boundary; the response then has through: null. An explicit through remains inclusive with at most 367 dates. Open-ended selections retain page, export and database timeout limits. A nonnegative period replaces the date interval; zero means the current period. The latest 100 available period IDs are returned. Optional locationKid, unitKid and userKid must be canonical KIDs in this bank. kind is all, debit (negative) or credit (positive). includeZero, includeBookings, includeMonthly default to true. Limit is 1–200 (default 50); offset is 0–100000. Rows are oldest first by MS2000, then location/unit. Continue toward newer entries with increasing offsets. Separate requests may shift as new postings arrive.
items contains the immutable posting KID, scope KIDs, recordedAtUtc, signed amountMinor, currency, description, transaction type, period, current display labels, reversed, optional reversalOfKid and canReverse. totals covers the full filtered selection, separately by currency. These totals are movements, not resident balances; no currency conversion is performed. Portal amounts display legacy hundredths as amountMinor / 100. Labels are current Log7/Log24 values, not historical snapshots. Modern JSON, plain legacy text and JSON wrapped in a legacy prefix/start-code envelope are supported.
recordedAtUtc / MS2000 is event time, not insertion time. Postings can arrive minutes or days later. Never use the highest MS2000 as a watermark for all new database entries. Each page includes a revision for the entire filtered set: identities, periods and monetary totals by currency. It is independent of offset/limit and is neither a cursor nor an access grant.
Log1 caching (source change for alfa; not yet released to beta/production). A positive Period is a closed set: its postings and membership cannot change, so authorized raw selections may be cached without time expiry. Existing raw Period = 0 postings may be reused for at most one hour per row, measured from that row's load time. This does not cache the whole list for an hour: each Data read checks current matching membership and numeric metadata through SQL. New, expired or metadata-changed rows are loaded; rows that moved to a closed period or no longer match are removed from the open selection. Adding a new row never extends older rows' expiry. Both use one shared, on-demand 1 GiB memory budget per tenant/API instance, with at most 8192 selections and least-recently-used eviction; entries do not survive an API restart. Cache identity includes tenant, bank, period, authorized scope and every stable filter used when loading. Period discovery remains fresh and never uses the highest MS2000 as an arrival watermark: a new period can contain older event timestamps. Current access, retention/anonymization, labels and refund status are applied separately. Oversized selections and unsupported legacy currency forms use the existing SQL path. HTTP responses remain no-store. Normal polling and the separate revision-cache timing below still apply; the one-hour raw-posting lifetime does not postpone new-row discovery.
GetBankAccountRevision: GET /account/revision with the same filters and permissions. Returns only {"revision":"..."}. Revision reads for identical authorized selections are shared for at most 30 seconds per API instance; every request rechecks access. Poll no faster than every 30 seconds and pause hidden views. On change, reload the loaded range from offset 0. Combine only pages with equal revisions and replace the old list only when all required pages are ready. If the revision changes during loading, discard the incomplete result and retry later with backoff.
dayCount returns {through, entries} from the same filtered snapshot as the page. through is the last returned posting's calendar date in timeZone; entries counts all matching postings through that entire day, including earlier matching days and unloaded rows. Every filter, permission and retention rule still applies, including settlement period. Do not use the lookahead row to advance the day. Empty pages return {through:null, entries:0}. For a scrolling counter, show the number of loaded rows followed by the latest nonempty page's dayCount.entries. Keep the denominator on the same day and increase it when another day is loaded. Replace rows and counts together only after reconciling equal revisions; full-selection totals remain unchanged.
const check = await fetch(`${accountUrl}/revision?${filters}`, {
headers: {Authorization: `Bearer ${accessToken}`}, cache: 'no-store'
});
if (check.status === 401 || check.status === 403) {
clearAccountView(); // remove data and handle login/access
} else if (!check.ok) {
showRetryLater(); // on 503, wait and increase backoff for repeated errors
} else if ((await check.json()).revision !== page.revision) {
await reloadLoadedAccountPages(); // offset 0; require equal revisions on all pages
}
Updates are not instantaneous: polling plus the shared cache can delay detection by approximately one minute. Revision checks inspect the filtered Log1 set and assume no maximum arrival delay. Names and reversal flags can change independently of the revision; reload as needed and always recheck commands on the server. Under continual changes or timeouts the old view is retained with retry available. CSV/XLSX remains a single database-snapshot export.
ExportBankAccount: GET /account/export with the same filters and format=csv or format=xlsx. Pagination is ignored. It returns the complete selection in one snapshot, at most 10000 rows and 4M description/name characters. Oversized exports fail, never silently truncate. Money columns use signed minor units, dates are UTC, identifiers/headers are stable. CSV neutralizes spreadsheet formulas; XLSX uses text cells for untrusted values.
ReverseBankAccountEntry: POST /account/{transactionKid}/reversal, without a request body. Additionally requires a bank-wide grant and Bank/User Write. Only recognized negative resident consumption with internal physical/activation tags can be reversed. The server locks and rechecks the original, appends the opposite signed amount in the current period, retains document/program metadata and requests balance/access synchronization. The original entry is preserved. Payment-provider transfers, anonymous/system users, credits, monthly transfers, unknown transaction types and already reversed entries are unsupported. canReverse is only a display hint; the command always validates again.
// Only after your own UI/user has reviewed and confirmed this exact entry.
const reversed = await fetch(`${accountUrl}/${encodeURIComponent(entry.kid)}/reversal`, {
method: 'POST', headers: {Authorization: `Bearer ${accessToken}`}
});
if (!reversed.ok) {
const problem = await reversed.json();
throw new Error(problem.code || `HTTP ${reversed.status}`);
}
Errors: 400 invalid filter/KID/time zone; 401 expired, stale or inactive session; 403 insufficient Tab/resource/operation grants; 404 missing posting; 409 already-reversed; 413 data-limit; 422 reversal-unavailable; 503 storage/write connection unavailable or nontransactional storage. Framework validation errors use the standard ProblemDetails errors object. Never automatically retry a financial write, including after timeout: refresh the list and review its result first.
Limits: read/write only Log tables; no schema changes, provider refunds, bank-to-bank transfers, balance reset or direct hardware delivery. InnoDB is required for financial writes; queued synchronization is not confirmation of delivery. At most 4096 filter labels and 100 currency groups. No caching or polling. The portal's print/PDF action prints only the loaded page; use export for the full selection.
Incremental bank search
eTab.Banks2 (5) is returned in profile tabs and tabDetails when granted to the manager in Log7. Global Search requires Bank Read, at least one current Tab and the manager's resource grants.
SearchBankActivation has a separate limit: 5 calls per 10 minutes and 20 per hour per manager in the tenant-bound API process, using fixed windows. All attempts count, including malformed and valid codes. Changing tokens or source IP does not reset the quota. HTTP 429 supplies Retry-After in seconds; wait at least that long before the next code attempt. Name searches remain available. The portal only sends code-shaped numeric queries to this provider and stops code requests during cooldown. Quotas are held in memory: restart resets them, and multiple API replicas require a shared limiter for an aggregate quota.
Call GET /api/v1/search/banks?q=Kombine (SearchBanks) and GET /api/v1/search/bank-activation?q=CODE (SearchBankActivation) concurrently with the same manager bearer session. Display each response immediately and merge items by kid. Each item contains kid, kind, name, zip and icon (the bank eSetting.Icon from the same Log24 query). Code matches have an empty icon; clients can use a default bank icon; kind is the enum name Bank. GetSearchBank: GET /api/v1/search/banks/{bankKid} resolves an authorized bank result before opening it.
Requires an active manager, at least one current Tab, PermissionBank2 Read and a matching site/bank grant. A location grant permits discovery of its parent bank only, without granting other locations. Every request checks the bounded session snapshot. The hostname determines the tenant.
Queries are trimmed and must contain 2–128 characters. Bank names and settlement emails use literal, case-insensitive substring matching. Only current bank-level Name, Icon and SettlementEmails in Log24 are read. The zip field remains empty for compatibility; banks have no postcode. Location postcodes are not searched. Values are, supporting JSON and legacy text. A text search returns at most 50 items; hasMore asks the caller to refine the query. A 60-second scope-specific cache coalesces simultaneous refreshes. The portal debounces input by 300 ms and ignores stale responses.
Bank codes are decoded with Kombine.Flex.Activation, then resolved in the same 60-second scoped Log24 cache as name searches. Results include the bank name and icon; zip remains empty. Invalid or unauthorized codes skip the bank lookup. Missing banks return no items. Bank, location and resident results are implemented. Errors: 400 query/KID, 401 session, 403 permission, 503 temporary storage failure. Retain other provider results on failure; avoid immediate retry loops.
SearchBanks also searches eSetting.SettlementEmails in Log24. Email search requires a whole-bank or tenant grant; location-only access permits bank-name discovery only. Results include matchedSetting (Name or SettlementEmails) and matchedValue containing the name or first matching email in the semicolon-separated list. Name matches take precedence. Render as text, never HTML. Example: GET /api/v1/search/banks?q=accounts%40example.test. The same cache, limits and error statuses apply; typing does not issue a new SQL query per keystroke.
Location search
GET /api/v1/search/locations?q=0123 (SearchLocations) runs independently of SearchBanks. It searches Log24 Name, Bank (alternative bank name), Zip, Address, VismaCustNo and TeltonikaSMS. Requires manager bearer, a current Tab, Location Read and a matching location grant. RetentionDays applies. Trimmed query 2–128 characters, literal case-insensitive substrings, at most 50 items plus hasMore. Results contain kind=Location, canonical kid, name, icon, zip and matchedSetting/matchedValue, with field priority in the order above. Render as text. Example: HTTPS GET with Authorization: Bearer and a URL-encoded q value.
GET /api/v1/search/location-activation?q=... (SearchLocationActivation) decodes via Kombine.Flex.Activation and resolves name/icon in the location cache. Location codes contain bank/location, not tenant; only the configured site is searched. Invalid, absent or inaccessible locations return no items. Bank and location codes share 5 calls per 10 minutes and 20 per hour per manager. Every code call counts; 429 includes Retry-After. The browser selects one code provider per input. 400: input; 401: reauthenticate; 403: permission; 503: temporary failure. Preserve other partial results on error. The 60-second cache coalesces misses; no query per location. Rate limits remain per-process and require shared storage for multiple replicas.
All bank and location searches, including activation lookups and GetSearchBank, include only BankId >= 1000. Special banks below 1000 are excluded.
Resident search
Resident results also include number from eSetting.Number. The portal displays Number · Name, omitting empty or duplicate parts. name retains its existing meaning; number is null for other result types.
Resident search and resident activation-code search also return parent banks with isContext=true when Bank Read is granted. At most 50 resident matches plus distinct banks; hasMore counts residents. Merge banks by kid with other results, including when direct bank search is disabled. Context banks do not include contact data.
A complete email address uses an exact case-insensitive match through the Log7 text index. Only names and TagIds support partial matching.
GET /api/v1/search/users?q=anna (SearchUsers) runs independently of banks/locations. Use Authorization: Bearer. Searches current Log7 Number, Name, Email, SMS and Tags. Number and email require exact case-insensitive matches; names allow literal substrings. TagId allows partial decimal IDs and spaces, but not hexadecimal. Name/TagId queries allow 10 seconds SQL and 12 seconds including queue time. Tags use the resident-list JSON/legacy parser.
Requires Users2, User Read and tenant/bank access or an Access/NoAccess association with a granted location. Ordinary users only, BankId >= 1000, RetentionDays applies. Maximum 50 visible results; up to 501 candidates examined. hasMore requests refinement when either bound is reached, so broad queries may omit matches. Returns kind=User, kid, name (number fallback), icon and matchedSetting/matchedValue, not other contact fields or tag lists. Priority: Number, Name, Email, SMS, Tags.
GET /api/v1/search/user-activation?q=... (SearchUserActivation) decodes via Kombine.Flex.Activation and resolves name/icon. Codes contain bank/user, not tenant; only the configured site is searched. All three code providers share 5 calls/10 minutes and 20/hour per manager. Invalid/invisible codes return no items. Errors: 400 input; 401 login; 403 access; 429 wait Retry-After; 503 temporary failure. Preserve other results. Cache 60 seconds per query/bank scope coalesces calls; no per-resident SQL. Quota remains per-process.
SearchLocations and SearchLocationActivation also return parent banks when the manager has Bank Read. Banks have isContext=true and contain name/icon, not contact data. At most 50 locations plus their distinct banks; hasMore counts locations. Merge by kid across responses, place each bank before its locations, and prefer direct bank matches over context explanations. Banks reuse the same 60-second cache as bank search. They are included even when only location search is enabled.
for (const item of response.items) {
if (!byKid.has(item.kid) || !item.isContext) byKid.set(item.kid, item);
}
SearchUserSms
GET /api/v1/search/user-sms?q=51573605 (SearchUserSms) is an independent fast provider with the same authorization, retention and parent-bank context as SearchUsers. It uses exact Log7.Text index lookups for plain and JSON values, normalizing spaces, hyphens, parentheses, leading + and international 00. Eight Danish digits match with and without 45. Accepts 8–15 digits; invalid format returns no items. Merge by kid. An independent 60-second cache and gate prevent slow substring/TagId queries from blocking SMS results. SearchUsers retains substring and TagId search and may still time out; keep SMS results on 503. Same 400/401/403/503 handling as SearchUsers; no activation quota is consumed.
Account endpoints retain HTTP 403 and code forbidden. After tab and bank-scope checks, the response may also include reason: missing-bank-read, missing-location-read, missing-unit-read or missing-user-read. Show a localized explanation; retain a generic denial for unknown reasons. No account data is read on denial.
Bookings: HTTP 403 retains code forbidden. After tab and bank-scope authorization, reason may be missing-location-read, missing-unit-read or missing-user-read. Localize the reason; use generic denial for unknown reasons. No booking data is read on denial.
GetCurrentManager returns Tabs and TabDetails ordered by eTab AttributeMetaSortOrder, then numeric tab ID. Missing metadata defaults to zero. Clients can display tabs in response order; permissions are unchanged.
SearchBanks, SearchLocations and SearchUsers accept complete canonical Kids and ToBankId (166.2000), ToLocationId (166.2000.4), ToUserId (166.2000-1100). Kid matches are exact, with matchedSetting=Kid and the readable identity in matchedValue. Existing site, tab, read, resource and retention checks still apply. Wrong tenant/type or inaccessible identities return no results. Resident lookup uses exact bank/user filters. Location/resident results retain authorized parent banks. No activation decoding or activation quota is used. HTTP errors and other text searches are unchanged.
GET /api/v1/search/users?q=166.2000-1100
SearchUsers supports kidOnly=true for direct resident Kid lookup even when ordinary resident search is disabled. Non-Kid input returns no items without business storage. Existing permissions apply; the toggle stays unchanged.
GET /api/v1/search/users?q=166.2000-1100&kidOnly=true
Kid search also accepts bank, location and resident identities without tenant: 2000, 2000.4 and 2000-1100. Kombine.Flex.Kid parses the identity; a missing tenant is filled exclusively from trusted API site configuration. An explicit tenant is preserved and checked. kidOnly=true also accepts tenant-relative resident IDs. Authorization is unchanged.
GetLocationUnits retains HTTP 403. After tab and resource checks, reason may be missing-location-read or missing-unit-read. Clients may show a localized explanation and use generic denial for unknown reasons. No location or unit data is read on denial.
{"status":403,"reason":"missing-unit-read"}
Account endpoints return HTTP 503 with code periods-timeout when the period query exceeds 10 seconds, storage-timeout for other SQL command timeouts, and storage-text-comparison for incompatible text collations. Show localized explanations and avoid repeated automatic retries. Raw SQL/database errors are not exposed. Date filters do not narrow the period lookup.
Account period choices use bank LogA (LocationId=0, UnitId=0, Period>0), up to 100 newest periods. Period zero remains selectable as the current period. Bank-wide access needs no Log1 lookup for this list. Location-limited access additionally checks for an authorized Log1 posting in each offered period. Entries, totals and revision still use Log1 with unchanged authorization.
Resident balance batches
GetBankUserBalances: POST /api/v1/banks/{bankKid}/users/balances is read-only. Send 1–50 canonical resident KIDs from the same bank, as returned by GetBankUsers. Numeric IDs and readable aliases are rejected. Duplicates appear once, preserving first-requested order.
const response = await fetch(`${apiBase}/api/v1/banks/${bankKid}/users/balances`, {
method: 'POST',
headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ userKids: visibleResidents.map(resident => resident.kid) })
});
if (!response.ok) throw new Error(`Balance request failed: ${response.status}`);
const { items } = await response.json();
// Use item.balances: one balance per currency. Never add different currencies together.
Requires an active manager, eTab.Users2, User Read and a bank-wide resource grant. A location-only grant cannot expose a balance across all locations. Permissions are checked on every request. Deleted residents follow the manager's retention rule. Missing or hidden residents return not-found and null, never a fabricated zero.
Use balances, containing one row per currency with currency, currentBalanceMinor, previousBalanceMinor, previousPeriod and previousPeriodIsProvisional. Amounts are signed 64-bit integers in the system's existing minor units (e.g. øre for DKK). No currency conversion occurs; never add different currencies together. Currency codes come from Log1 and are decoded, trimmed and uppercased. Missing/empty codes form a separate currency:null row; no currency is inferred. Rows are sorted by currency code.
The resident discount applies to DKK only. It is added once to the DKK row, which is also created when the resident only has postings in other currencies. An existing resident with no postings and no discount receives balances:[]. Missing/hidden residents also have an empty list, but their status is not-found.
Currency balances use period zero and FlexOrm's missing-settlement correction. Receipt documents are grouped by DocId and their settlement boundary is determined before separating the amounts by currency. Correction history applies tenant limits with positive manager overrides. The provisional-period discount cap uses only its DKK amount. These balances are not an instruction to charge.
Only selected residents are read in shared queries, reusing bank settings within the request, without a shared balance cache. At most two balance batches run per API process, waiting at most one second for capacity, with a 20-second database deadline. Correction history is capped at 50,000 lines per request. The portal resident list renders rows first, then loads current balances in batches of at most 10 residents, one batch at a time. Rows added by scrolling are handled the same way. Balances reload when filtering, sorting or navigating; the list does not poll balances. The API limit remains 50 residents per request.
400: invalid list/KID; 401: expired session; 403: insufficient permission; 413: oversized request. A 503 with storage-busy, storage-timeout, balance-batch-too-large or storage-unavailable returns no partial balances. Reduce oversized batches; back off before a bounded retry after busy/timeout responses. Display failure instead of zero. No database writes are performed.
Existing scalar fields on the resident result, request shape and operation ID remain unchanged for compatibility. The scalars retain the old calculation across currencies and must not be interpreted as one currency's balance; use balances. Both periods and every currency reuse the same Log1 query grouped by resident, period and currency, with no extra query per currency. At most 100 currency buckets are allowed per resident.
All currency rows use the resident's same latest positive period, even if a currency last appeared in an older period. No posting for that currency in the selected period means a balance of 0 for that period. No previous period remains null. Clients should not fall back to the old mixed amounts if the currency list is absent.
The previous period is the resident's highest positive period number, even if the bank has newer periods. A stored period's balance is its sum without adding the discount again. When no previous period exists, both its balance and period number are null, and the provisional flag is false. This includes residents with only period zero or no postings. A previous period with a zero balance instead returns 0 and its period number.
Delayed settlement produces a provisional previous balance using FlexOrm document grouping and capped discount. This also applies to cash banks, whose current balance stays unchanged. previousPeriodIsProvisional=true identifies a period computed only in memory; it has not been stored or settled. Its number is the bank's highest Log1 period plus one and must not be used as an existing settlement/download identifier. That number uses one indexed MAX lookup shared by the batch, only when a correction might be needed. A provisional period can have a zero balance.
GetBankUserBalances also returns latestPostingMs2000 (UTC milliseconds since 2000-01-01; zero means no Log1 postings) and hasActiveSubscription (active card/SEPA subscription). Both fields are null for missing/hidden residents and share the balance permissions and snapshot. Active status follows Orders: CardSubscription or SepaSubscription, Flags > 0, CR2000 > 0 and ActionCode OK/AUTHORIZE. It is not proof of payment. On HTTP 503, show unavailable and retry; never assume inactive or zero. Included in all client variants 0.4.2 for this beta release.
Installers — GetInstallers
GET /api/v1/installers?includeActivationCode=true adds items[].activationCode (the user activation code) and additionally requires Installer Create. Default false omits codes; missing Create returns 403 missing-installers-create. Codes are generated for authorized, retention-visible rows only. Do not log or cache them; passwords are never returned. The activation-code column is display-only, not a supported sort.
GetUserCount — GET /api/v1/users/count returns {count, iconKid} for active residents visible under UserFinder1, User Read and the current tenant-bound bank/location scope. The approximate badge count is cached in memory for up to 24 hours per scope; restart or eviction causes a fresh count. Deleted residents and list filters are excluded. Authorization is checked on every request. Each HTTP request waits up to 12 seconds; a shared count may continue for up to 60 seconds even after navigation or a request timeout. At most one count runs per tenant process, with at most 16 pending exact scopes. 401/403 means access denied; 503 means the result is not available yet or counting failed. Retry with increasing delays (for example 2, 5 and 15 seconds), preserving the last same-scope count or showing unknown, never zero. Example: curl -fsS "$API/api/v1/users/count" -H "Authorization: Bearer $TOKEN".
Installers default to eIcon.worker when the stored icon is missing, empty or invalid. A valid explicitly stored icon is preserved.
GET /api/v1/installers requires an active manager, Installers1 (68), independent PermissionInstaller2.Read and a whole-tenant KID grant. Bank-only or location-only access is insufficient. Account, credential stamp, tab, rights and scope are checked on every page through the bounded manager snapshot. The icon can be changed with SetInstallerIcon as described below.
The response is {items: [...], nextCursor: ...}. Each item contains kid, name, icon, email, locations, tags, deleted, deletedAt, enabled, lastActiveAt. All object identifiers are canonical KIDs; derive the displayed numeric UserId from the installer KID. Location and tag entries contain kid and enum-name state. They retain NoAccess and locked/deleted/history states: they describe the installer, not the caller's permissions. Location names are not looked up.
The trusted site's A{TenantId:D4}.Log7 is read with BankId=TenantId and eUserId.Installeres..InstalleresLast (1–999). Manager authorization settings still use bank zero. No credentials are selected. Disabled installers are included. Deleted rows follow the caller's RetentionDays; invalid/future deletion values are hidden. Missing Deleted means zero. Missing/invalid Enabled is null. Alive uses the current krumb's MS2000, never Text; absent, nonpositive or unrepresentable timestamps are null. UTC timestamps should be displayed in the viewer's time zone. Reads do not update Alive.
pageSize: 1–250, default 50. Follow nextCursor until null, including empty pages. Cursors bind caller, tenant, filter, ordering (page size may change).
filter: literal Name/Email substring, case-insensitive, trimmed, maximum 128 characters without controls. Escape URL parameters. SQL wildcard characters are literal.
sort: identity (default), name, email, locations, tags, deleted, enabled, lastActive; direction: asc (default) or desc. Ordering applies before paging. Name/email use ordinal case-insensitive comparison. Locations/tags compare sorted numeric ID/state lists lexicographically; deleted compares timestamps; enabled compares null/false/true; activity is chronological. Identity breaks ties in the same direction.
Identity ascending uses bounded keyset reads. Other orderings use a tenant-local index of at most 999 entries, cached for 60 seconds, then fresh page details with retention reapplied. Null sorts first ascending. Changes are not a frozen snapshot; restart if a cursor anchor disappears.
let cursor = null;
do {
const query = new URLSearchParams({pageSize: '50', sort: 'name', direction: 'asc'});
if (cursor) query.set('cursor', cursor);
const response = await fetch(`${api}/api/v1/installers?${query}`, {
headers: {Authorization: `Bearer ${token}`}
});
if (!response.ok) throw new Error(`GetInstallers: ${response.status}`);
const page = await response.json();
renderInstallers(page.items);
cursor = page.nextCursor;
} while (cursor);
Errors: 400 invalid-page/invalid-filter/invalid-sort/invalid-cursor (correct input or restart); 401 (log in again); 403 missing-installers-tab/missing-installers-read/missing-tenant-access (request the missing access); 503 installers-unavailable (storage failure or 12-second deadline, retry manually). Responses are no-store. No partial sorted results, background retry loop or write operations.
Installer details and icon — GetInstaller / SetInstallerIcon
GET /api/v1/installers/{installerKid} requires the same read access as the directory. The response contains installer, canEditIcon, iconRevision and availableIcons. The KID must be a canonical Installer KID for the site's tenant, with BankId equal to TenantId and a UserId in the installer range. Missing or retention-hidden installers return 404.
The icon catalogue uses the same metadata as the manager picker: all eIcon entries with eIconSubject.Person. A valid current icon without Person metadata appears first, but cannot be assigned again. POST /api/v1/installers/{installerKid}/icon requires both Installer Read and Write, tab 68 and whole-tenant access. canEditIcon is only a display hint; the API rechecks current account, rights and retention access during the save.
const detailResponse = await fetch(`${api}/api/v1/installers/${installerKid}`, {
headers: {Authorization: `Bearer ${token}`}
});
if (!detailResponse.ok) throw new Error(`GetInstaller: ${detailResponse.status}`);
const detail = await detailResponse.json();
const response = await fetch(`${api}/api/v1/installers/${installerKid}/icon`, {
method: 'POST',
headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json'},
body: JSON.stringify({icon: selectedPersonIcon, expectedRevision: detail.iconRevision})
});
if (!response.ok) throw new Error(`SetInstallerIcon: ${response.status}`);
const confirmed = await response.json();
renderInstallerIcon(confirmed.icon); // Apply only after a successful response.
The save changes only eSetting.Icon and returns kid, icon, iconRevision, availableIcons. An unchanged icon produces no history row. Other fields, location access and tags cannot yet be edited here.
400: invalid-installer-kid or invalid-installer-icon. 401 requires a new login. 403: missing-installers-tab, missing-installers-read, missing-installers-write or missing-tenant-access. 404: installer-not-found. 409: installer-icon-conflict; reread before selecting again. 503: installer-icon-unavailable. Keep the previous selection on failure; reread after an uncertain network outcome, and never retry a write automatically.
Administrators — GetManagers
Directory items and GetManager now include operationPermissions and retentionDays for the displayed administrator. The seven categories Managers, Bank, Location, Unit, User, Installer and Service reflect current Log7 PermissionManagers2, PermissionBank2, PermissionLocation2, PermissionUnit2, PermissionUser2PermissionInstaller2 and PermissionService2. The resource, level, flags and six can* fields have the same format as GetCurrentManager. Flags are independent: Write does not imply Read; missing/empty settings default to Read; invalid settings return null flags and no operations. Combine these flags with account state, tabs and Kids.
retentionDays is the displayed administrator’s number of days for viewing otherwise authorized deleted records. Missing values default to 10 days; invalid or negative values become 0. Explicit 0 is preserved. It does not schedule physical deletion. The signed-in caller still uses their own permissions and RetentionDays to read the administrator; viewing an account never grants that account’s permissions. Values are read with the other details in the same Log7 query; the sorting index is unchanged. RetentionDays remains read-only; permission editing is documented below. Read status codes are unchanged. Keep using the canonical manager Kid in the curl example below.
GetManager: GET /api/v1/managers/{managerKid} reads one administrator with the fields and authorization requirements of a directory item, plus the availableTabs catalog described below. Use its canonical kid from the list. A different-site KID or one outside the manager range returns 400 invalid-manager-kid. An absent administrator or a record outside retention returns 404 manager-not-found; the next administrator is never substituted. Handle 401, 403 and 503 as for the list. At most one Log7 candidate is read; no database values change.
The portal uses this operation for workspace shortcuts under Administrators. Shortcuts are local to the browser session, tenant and signed-in manager. They never grant access; each visit is rechecked by the API. The administrator overview currently supports reading only.
filter searches the entire administrator list for a case-insensitive substring of Name or Email. Maximum 128 characters; surrounding whitespace is removed. An empty filter lists all permitted entries. Filtering happens before the page limit; %, _ and ! are literal characters. Start without a cursor when changing the filter, and keep the same filter on following pages. Control characters or excessive length return 400 invalid-filter.
Each item also includes organisation, enabled, deleted and deletedAt. Organisation is empty when absent. Enabled is true for 1, false for 0, and null for missing/invalid values. Deleted is true for a positive deletion timestamp; deletedAt is then that UTC timestamp, otherwise null. These fields alone do not prove the account can sign in. Display unknown Enabled as unknown, and continue to enforce the documented permissions. Deleted entries remain limited by the caller’s retention allowance.
GET /api/v1/managers?pageSize=50 reads current tenant Log7 settings, bank zero, in the inclusive eUserId.Managers–eUserId.ManagersLast range. Root, resident and service accounts are outside this range. Items contain kid, name, icon, email, resourceGrants and tabs. Passwords are never returned.
Requires an active manager session, eTab.Managers1 (28), PermissionManagers2 Read and an explicit tenant-wide Kid grant. Bank/location grants are insufficient. Write does not imply Read; absent permission values default to Read. Every page rechecks these requirements using the shared session snapshot, at most 60 seconds old.
let cursor = null;
do {
const url = new URL('/api/v1/managers', API_BASE);
url.searchParams.set('pageSize', '50');
if (cursor) url.searchParams.set('cursor', cursor);
const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw new Error(`GetManagers: ${response.status}`);
const page = await response.json();
renderAdministrators(page.items); // Use textContent, never HTML from data.
cursor = page.nextCursor;
} while (cursor);
For user interfaces, request each following page near the bottom of the list. pageSize is 1–250, default 50; pageSize may change between requests. The opaque nextCursor is bound to the tenant, caller, filter, sort and direction. Follow it even after a short or empty page, until null. Restart without a cursor when changing these parameters. Pages are not a frozen snapshot of concurrent changes; if the continuation identity is absent from a refreshed index, 400 invalid-cursor requires restarting the list.
lastActiveAt in both GetManagers and GetManager is the last recorded activity: MS2000 on the current eSetting.Alive Log7 row, BankId 0, converted from milliseconds since 2000-01-01 UTC. It uses the row timestamp, not its Text value or other profile changes. Missing, nonpositive or unrepresentable timestamps return null; display these as unknown. Display valid UTC timestamps in the viewer’s local time zone. Reading does not update Alive, and this value is not proof that the administrator is online. sort=lastActive orders chronologically; unknown times come first ascending and last descending. The sorting index may be up to 60 seconds old while page details are read afresh.
sort=identity|name|email|organisation|kids|deleted|enabled|lastActive and direction=asc|desc order the complete permitted result before paging. The API default remains identity/asc; the portal uses name/asc. Name, email and organisation use case-insensitive ordinal comparison. Kids compare numerically sorted bank/location scopes for the current site, irrespective of stored Log7 order; empty scopes come first. Enabled orders unknown, false, true; Deleted orders by deletion timestamp, with active records first. Manager identity breaks ties; desc reverses the entire order.
Selectable ordering uses a shared seven-setting Log7 index cached for at most 60 seconds per filter. Only the selected page’s details are fetched afresh; access and deletion retention are rechecked each time. Indexes allow at most 20,000 matching identities, within a 50,000-weighted-entry cache (minimum weight 100 per filter). Concurrent index reads are coalesced; data failures delay new index reads for five seconds. A cold cache may need an extra query; the overall request deadline is 12 seconds. Identity/asc retains one bounded query per page. There are no total counts or per-manager queries.
Disabled administrators remain listed. Deleted administrators follow the caller’s RetentionDays; malformed deletion settings are hidden. Site-relative Kids are resolved to the API site, and only valid grants for that site are returned. Tabs follow AttributeMetaSortOrder, then numeric identity. These are assigned scopes and pages, not proof of effective operation permissions.
400 (invalid-page/invalid-cursor/invalid-sort): restart with valid parameters. 401: sign in again. 403: missing-managers-tab, missing-managers-read or missing-tenant-access identifies the missing requirement; do not retry automatically. 503 (managers-unavailable): show an error and offer a bounded retry with the same cursor. 503 manager-directory-too-large: narrow the filter and restart; the API never silently truncates a sorted list. The listing operation only reads data. Permission editing is described below.
Service comes from eSetting.PermissionService2 (3017) in current bank-zero Log7 and is returned by GetCurrentManager, GetManagers and GetManager. It uses the same six independent flags and missing/invalid-value rules. It does not enable service login or grant rights in other categories. Update it through SetManagerPermission with resource Service; existing authorization, concurrency and error handling apply.
Edit administrator permissions
SetManagerPermission: POST /api/v1/managers/{managerKid}/permissions/{resource}. Requires an active session, tab 28, a tenant-wide grant and both PermissionManagers2 Read and Write. Your own permissions are editable only if you are the sole active, non-deleted administrator with whole-tenant access. Every ordinary authorization requirement still applies. GetManager and directory items include isCurrentManager and canEditPermissions as display hints; the API rechecks the current account, credential stamp, tab and access inside the write transaction.
The exception checks other administrators’ Kids, Enabled and Deleted in the tenant’s bank-zero Log7. Only active accounts with an explicit whole-tenant grant count, regardless of their tabs or operation flags. Bank/location-only grants do not count. Directory filters, retention and cached counts never establish the exception. Writes lock the relevant records and ranges in the same serializable transaction as the change; a previously allowed display hint is insufficient. A read response containing your own record and Managers Write needs one extra bounded query for this hint. At most 20,000 other scope records are examined; if the absence of another administrator cannot be confirmed within this bound or the deadline, the request fails with 503.
Read GetManager first. Choose resource: Managers, Installer, Service, Bank, Location, Unit or User. Send one flag (Read=1, Write=2, Create=4, Delete=8, RenameExtrenatId=16, Rename=32), the desired enabled boolean and the category's displayed expectedFlags. The field is required, including explicit null for malformed stored rights. Only the selected bit changes; Write does not imply Read.
200 returns the saved category. Update the checkbox only after a valid OK response. Storage follows theme changes: append bank-zero Log7 history with the caller as actor and verify the current Log7 trigger before commit. Unchanged values append nothing. Tenant comes exclusively from server configuration. The target's local session cache is invalidated; other API instances may retain a read snapshot for up to 60 seconds. Permission writes always use fresh authorization. Disabled targets may be edited; deleted targets follow the caller's RetentionDays.
400: invalid KID, category, flag or input.
401: sign in again.
403: own-manager-permissions when another active administrator also has whole-tenant access, or missing tab, Read, Write or tenant-wide access. Refresh the card; do not retry automatically.
404 manager-not-found: absent or retention-hidden target.
409 permission-conflict: reload and review current permissions before trying again.
503 manager-permissions-unavailable or timeout: retain the displayed checkbox and show an error. A lost response may follow a committed write; reread before manually retrying. Never retry automatically.
A configured write connection and transactional Log7 tables are required. Only the seven Permission*2 settings can be edited here; names, Kids, tabs and other administrator fields are outside this operation.
Combine role (unreleased)
SetManagerPermissionRole — POST /api/v1/managers/{managerKid}/permission-role. The combine preset grants all six flags (63) in all nine permission categories, selects every current available tab, and adds the site Tenant KID for all banks in one atomic Log7 transaction. Send expectedTabsRevision and expectedKidsRevision from GetManager along with all nine expectedFlags. Existing active-account, Managers1, whole-tenant, Managers/Tabs/Kids Read+Write and own-edit checks still apply. Narrower site grants are replaced; foreign stored entries are preserved without granting access to other tenants. Future tabs are not selected automatically. The response adds resourceGrants, kidsRevision and canEditKids; validate the full permissions, tabs and grants response before updating the display. Missing revisions return 400 invalid-permission-role; stale values return 409 permission-conflict, tabs-conflict or kids-conflict; malformed storage returns invalid-stored-tabs or invalid-stored-kids. Nothing is partly saved. On 409 reread and review; on 503 or an uncertain response reread before a manual retry. No automatic retries. Account state and profile fields remain unchanged.
The operation permission matrix now has nine categories: Managers, Bank, Location, Unit, User, Installer, Service, Tabs and Kids. Role requests to SetManagerPermissionRole must send all nine expectedFlags, including the last displayed Tabs and Kids masks (explicit null for malformed values). Missing stored values default to Read (1); invalid values grant nothing. Operator, technical-support and tenant-accounting set all nine masks to 63; accounting and caretaker set Tabs/Kids to Read (1). SetManagerTab and SetManagerKid now additionally require the caller’s respective Tabs or Kids Read and Write, including transactional reauthorization. Every role replacement requires both Tabs and Kids Read/Write, rechecked inside the transaction, because all presets replace both permission masks. Accounting and combine replace tab assignments; other presets preserve them. Existing manager, tenant, own-edit and tab checks still apply. A denial returns 403 missing-tabs-read, missing-tabs-write, missing-kids-read or missing-kids-write. Respect canEditTabs and canEditKids independently of canEditPermissions/canEdit. These masks control editing assignments, not the caller’s existing navigation or KID scope; Read does not hide directory metadata. Create/Delete/Rename flags remain independent stored values and do not replace Write in assignment operations. No existing database values are migrated. This change is unreleased; update consumers before deployment.
The tenant-installer preset ({Tenant} - Installer) grants all six permission flags (63) in all nine categories, matching technical-support. SetManagerPermissionRole requires all nine expectedFlags and preserves existing tab selections and KID grants. Unreleased addition.
The new presets technical-support and tenant-accounting currently grant all six flags (63) in all nine categories and preserve tabs, matching operator. Both SetManagerPermissionRole accept these values with all nine expectedFlags. Unreleased addition.
Send all nine categories in expectedFlags, including Service. Missing or extra categories return 400 invalid-permission-role without writes.
Administrator role presets
SetManagerPermissionRole applies a complete preset in one call: POST /api/v1/managers/{managerKid}/permission-role. It uses exactly the same active-account, Managers1, Managers Read+Write, whole-tenant and own-card exception checks as SetManagerPermission. The API defines the masks; clients send the role identity, current expected masks and the required tab revision.
role
Bank
Location, Unit, User
Managers, Installer, Service
accounting (Regnskab)
Read (1)
Read (1)
None (0)
caretaker (Varmemester)
Read (1)
Read + Write (3)
None (0)
operator (Operator)
All six flags (63)
All six flags (63)
All six flags (63)
For accounting, also send the latest tabsRevision from GetManager as expectedTabsRevision. Existing clients must supply this new property when applying accounting. Missing or invalid revisions return 400 invalid-permission-role. The transaction validates both permissions and tabs before any write. A stale tab revision returns 409 tabs-conflict; malformed stored tabs return 409 invalid-stored-tabs. No part of the role is saved on either conflict. Read again and review before retrying. Set TABS_REVISION below to the revision you read.
Read GetManager first and copy all nine operationPermissions[].flags into expectedFlags, keyed by resource. Include explicit null for an invalid stored mask. The example assumes every currently displayed mask is 1:
The operation replaces all nine categories, including clearing extra flags, in one serializable Log7 transaction. Every expected value is checked before the first write, and each history append records the caller and verifies the current-table trigger before commit. No-op categories append nothing. The response contains role, all nine operationPermissions, tabs, tabsRevision, canEditTabs and canEditPermissions. Validate the complete successful response before updating permissions and tabs together. Use the returned tabsRevision for subsequent edits. Applying accounting or caretaker to yourself removes Managers access and returns canEditPermissions=false; disable further editing. Operator enables all 54 checkboxes, including Managers, Installer and Service, and retains Managers access. Accounting replaces the entire tab selection with exactly Users2 (53), Account2 (2) and Settlement2 (40), removing all other IDs, including unknown stored IDs. Other roles except combine preserve tabs. Kids, account status and profile fields stay unchanged. Roles are one-time presets, not stored memberships or automatic ongoing rules.
400 invalid-permission-role means an unknown role or missing, extra or invalid expected masks; malformed tenant/KID uses invalid-manager-kid. 401 requires login; 403 uses the same access codes as individual changes, including own-manager-permissions; 404 is manager-not-found. A mismatch anywhere returns 409 permission-conflict with no partial save: reload and review. On 503 manager-permissions-unavailable or an uncertain timeout, keep the previous display and reread before manually retrying. Never issue automatic retries or a sequence of individual bit calls as a replacement for the atomic preset. The existing 12-second deadline and sole-manager scan limit apply.
Edit administrator tabs
GetManager additionally returns availableTabs: every recognized numeric eTab except None and Length, ordered by AttributeMetaSortOrder then ID, with aliases deduplicated. Each item contains id, enum-derived name and iconKid. This catalog includes pages not yet implemented. Mark entries whose IDs appear in tabs. The directory omits the catalog; both reads return canEditTabs and the opaque tabsRevision.
SetManagerTab: POST /api/v1/managers/{managerKid}/tabs/{tabId}. Requires an active account, Managers1 (28), independent Managers Read and Write, and a whole-tenant grant. Own edits use the same sole active tenant-wide manager exception as permission changes. Display hints never authorize a write: the API rechecks the locked current account, tab, scope and permissions inside the transaction.
Read the target first, copy its exact tabsRevision, and choose an ID from availableTabs. The example grants tab 8:
TABS_REVISION='copy tabsRevision from GetManager'
curl -X POST "$API_BASE/api/v1/managers/$MANAGER_KID/tabs/8" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
--data "{\"enabled\":true,\"expectedRevision\":\"$TABS_REVISION\"}"
200 returns the saved tabs, next tabsRevision, canEditTabs and canEditPermissions. Update selection only after validating the successful response and use its revision for the next click. Removing your own Managers1 grant returns both edit hints false: lock all editor controls. Tab access is only one requirement; it does not grant Kids, account access or operation rights.
Only the requested tab changes. Unknown integer IDs and unrelated stored entries are preserved. The change uses the shared serializable bank-zero Log7 history transaction, caller attribution and verified current-table trigger; a no-op adds no history. Actor and target session caches are invalidated even on uncertain outcomes. Other instances may retain read snapshots for up to 60 seconds; every write rechecks current authorization. The 12-second deadline and sole-manager scan limit still apply.
400 invalid-manager-kid or invalid-tab-change: invalid/foreign KID, unavailable tab, missing boolean or invalid revision.
401: sign in again. 403: the same access codes as permission changes, including own-manager-permissions. 404: manager-not-found.
409 tabs-conflict: reread and review the latest selection. invalid-stored-tabs: stored JSON is not an integer array; no data was overwritten.
503 manager-tabs-unavailable, timeout or a lost response: retain the displayed selection and reread before a manual retry. Never retry writes automatically.
Administrator Kids
GetManager and GetManagers return resourceGrants, kidsRevision and canEditKids. Use SearchBanks and SearchLocations to find choices; their normal Read, scope and retention rules still apply. Residents and units are not valid resource grants.
SetManagerKid: POST /api/v1/managers/{managerKid}/kids. Requires an active manager, Managers1 (28), independent Managers Read and Write, and explicit whole-tenant access. Own edits require being the sole active tenant-wide manager. The API rechecks current Log7 snapshots inside the transaction.
A Bank KID grants the entire bank and replaces its individual location grants.
A Location KID grants only that exact location.
The site’s Tenant KID means All banks and replaces individual bank/location selections. Removing it later does not restore those selections.
enabled: false removes only the exact grant. Already covered additions are no-ops.
A confirmed 200 response returns the complete resourceGrants, next kidsRevision and canEditKids. Update selections only after confirmation. Removing your own tenant grant returns canEditKids=false; lock the entire editor. KIDs must be canonical and belong to the site tenant; clients cannot select a tenant. Added banks/locations must exist as exact Settings scopes in Log24. Removing stale grants is allowed.
Only Kids change through the existing audited bank-zero Log7 transaction. Tabs and other permissions are preserved. Stored site-relative grants resolve to this site; foreign stored entries are preserved without granting access here. Growth is limited to 1,000 Kids; removals and broader bank replacements remain allowed. Session and directory caches are invalidated; read caches on other API instances may live for up to 60 seconds. Every write reauthorizes.
400 invalid-manager-kid/invalid-kid-change: invalid/foreign identity, unsupported scope or missing boolean/revision.
401: sign in. 403: normal permission codes, including own-manager-permissions. 404 manager-not-found includes retention-hidden managers; resource-not-found means the selected bank/location does not exist.
409 kids-conflict: reread and review. invalid-stored-kids: invalid stored grants were not overwritten. kids-limit: too many grants.
503 manager-kids-unavailable, timeout or a lost response: keep the display, reread before a manual retry and never retry automatically. Writes have a 12-second deadline.
Deletion retention during a write and the confirmed canEditProfile hint use the same database clock as the deletion timestamp. An authorized caller can immediately restore another manager within their existing retention window, even when the API and database clocks differ slightly. Restore sends Deleted=false with the latest profileRevision; update the toggle only after a valid 200 response.
Edit administrator details
SetManagerProfileField: POST /api/v1/managers/{managerKid}/profile/{field}. Requires an active manager, Managers1 (28), Managers Read and Write and whole-tenant access. Own edits use the same sole active tenant-wide manager exception as permissions and tabs. These seven fields use Managers Write, without additional Delete or Rename flags. Every write rechecks the locked current authorization snapshot and target visibility.
First read GetManager. Its canEditProfile is a display hint; copy profileRevision exactly. Use the case-sensitive field names below:
field
JSON value
Stored meaning
Name / Organisation
String, up to 200 characters, no controls
Unicode/whitespace preserved; empty clears the field.
Enabled
true / false
1 / 0
Deleted
true / false
Server deletion time in MS2000 / 0
RetentionDays
Integer 0–2147483647
Days of visibility for otherwise authorized deleted records.
Icon
Exact eIcon name as a string
Only icons with eIconSubject.Person metadata may be newly assigned.
Email
One nonempty email address, up to 254 characters
Login address. No whitespace, controls or display-name syntax. Case is preserved.
Email format is validated before any database access: a plain ASCII internet address with at most 64 characters before @ and a fully qualified domain such as example.com. Domain labels contain 1–63 letters, digits or hyphens, with no leading/trailing hyphen. International domains use punycode. Empty addresses, name@company, repeated/leading/trailing dots, whitespace, quoted local parts and address literals return 400 invalid-profile-change. The stored address and revision remain unchanged. The portal shows a field error without sending a save request; a corrected address saves on the next blur. Other profile edits preserve existing legacy email values. This checks format, not mailbox existence.
Email edits use the same authorization and revision checks. The response includes the confirmed email. The password and existing sessions remain unchanged. The address is not verified and no email or invitation is sent by this edit. If multiple accounts later match the same email and password at login, the active, non-deleted manager with the newest Alive krumb MS2000 is retained and the other matching passwords are cleared as described in the login section. Invitations use the separate InviteManager operation.
GetManager.availableIcons contains all Person icons in numeric enum order. Mark the current iconKid. If it is outside the Person catalog, it appears first for display only; it cannot be newly assigned. Missing/unsafe filenames display as user without rewriting storage. The paged directory omits the catalog. Successful saves return iconKid and updated availableIcons. Change the selection only after a valid 200 response; preserve it on failure. Icon edits share revision protection and authorization with the other profile fields.
For deletion send {"value":true,"expectedRevision":"..."} to the /profile/Deleted endpoint. To restore, send false with the latest revision. The client never sends a deletion timestamp. The database server sets milliseconds since 2000-01-01 UTC; this is not Unix time. Repeating true preserves the first deletion timestamp. Restoration stores 0, never a boolean string. Only the selected field changes.
200 returns field, the seven profile values, deletedMs2000 (0 or timestamp), deletedAt (UTC or null), a fresh profileRevision and canEditProfile. Validate the complete response before updating the UI. False editability locks profile, permissions, role and tab controls. It occurs when disabling/deleting yourself or when deleting another manager hides them under your RetentionDays. Restore requires a caller whose existing retention includes that deleted manager; the write never bypasses retention.
The shared serializable bank-zero Log7 writer appends only changed settings, attributes the caller and verifies the current-value trigger before committing. It does not write legacy tables or alter passwords. Session and directory caches on this instance are invalidated even after an uncertain outcome; other instances can retain read snapshots for up to 60 seconds. Disabled/deleted accounts lose access at their next fresh authorization check; writes always reauthorize immediately. The 12-second deadline and sole-manager scan limit apply.
400 invalid-manager-kid or invalid-profile-change: wrong identity, unknown field, invalid type/range or missing revision/value.
401: sign in. 403: normal permission/own-card denial. 404 manager-not-found: absent or outside caller retention.
409 profile-conflict: one of the seven raw profile fields changed; reread and review.
503 manager-profile-unavailable or timeout: keep the previous state and unsaved drafts. A lost response may follow commit, so reread before a manual retry; never automatically retry.
MCP: read and write with manager permissions (unreleased)
Available in this source branch; not yet deployed. Configure an MCP client for https://api.{tenant}.kombine.technology/mcp (or the matching beta host) using Streamable HTTP. The endpoint is stateless: send each JSON-RPC message in a separate POST /mcp with the manager's Authorization: Bearer header. No MCP-Session-Id is needed. GET streaming, resumable sessions and server-initiated requests are not provided.
Obtain the opaque token with ordinary LoginManager; configure it as a secret HTTP header in the MCP host. The token is bound to this API site's tenant and environment. Use RenewManagerSession outside MCP before expiry and replace the configured header; MCP calls do not extend token lifetime. Login, password and token operations are excluded from the tool catalogue. This version has no OAuth discovery, client registration or browser consent flow: clients must support configured bearer headers. Adding the URL alone does not provide an automatic ChatGPT connector login.
tools/list returns an explicit catalogue of approved JSON business reads and writes. Tool names equal their stable OpenAPI operation IDs, such as GetCurrentManager, GetObjectAddress and UpdateObjectAddress. Path and query arguments appear at the root of arguments; the JSON request DTO appears under body. Use each returned inputSchema for field types and required values. File downloads, SVG/image endpoints, operator diagnostics, hosting/log operations, password recovery/change, email verification, InviteManager, GenerateServiceApiKey and AskPortalAssistant are excluded. JSON icon-status operations such as GetUnitIcons, GetLocationIcons and GetBankIcons are available. Discover the current catalogue rather than assuming every REST operation is available.
Every business tool executes the existing API operation with the caller's manager bearer session and the same bounded account, Tab, KID and operation checks. Catalogue visibility grants no access. An agent can modify only what that manager may modify; KIDs never grant permissions or select another tenant. Existing validation, revision protection, history and operation-specific limits still apply. Keep returned text as data and obtain the user's authorization for the intended changes in the agent host.
Copyable curl exchange
The following POSIX-shell example uses environment placeholders: set PORTAL_API_BASE to the trusted HTTPS API base URL, PORTAL_ACCESS_TOKEN to the current token and PORTAL_OBJECT_KID to an authorized canonical object KID. Keep tokens out of prompts, URLs and logs. The read examples do not modify data; the final example saves an address.
Use the protocol version returned by initialize in subsequent MCP-Protocol-Version headers. Accepted notifications return HTTP 202 with no body. Read the address tool's returned data.revision, then supply that exact value as expectedRevision:
The write requires the object's Read and Write permissions and the other address-operation access requirements. Refresh the revision before each subsequent edit. A successful save can still have a failed coordinate lookup; inspect data.outcome.
Results, errors and retries
The catalogue is shared metadata and is not filtered to the current manager's permissions; access is enforced on every call. Limits: 120 MCP requests per minute per manager, eight simultaneous MCP requests per API process with no queue, 128 KiB per MCP request and 256 KiB per business response. Smaller request limits and other bounds of the underlying operation still apply. A limit is a ceiling, not a recommended polling frequency.
A business result contains {status, data, truncated}: status is the underlying API HTTP status and data is its JSON response or ProblemDetails. Check both the MCP tool result's isError and the envelope; a successful MCP transport response does not establish a successful business operation. HTTP business failures and withheld oversized results set isError=true. truncated=true means the full response was withheld; narrow the query or use smaller pages. An ordinary hasMore flag still requires pagination.
Outer HTTP 401 means no valid manager bearer session: renew while unexpired, or log in again. A business 403 appears inside the tool result and means the manager lacks the operation's rights. A business 409 requires a fresh read and review of the concurrent change. HTTP 429 means throttling; honor Retry-After when supplied and reduce request frequency. Invalid tool names or arguments produce MCP errors. Never retry writes automatically after timeout, cancellation, a lost response or a 503: storage may already be committed. Read back first, then decide whether another write is needed. Cancellation does not undo an operation already committed.
Kombine.Flex.Portal.Client provides typed C# methods for all 235 public integration operations, including anonymous public calls. One NuGet package contains .NET Standard 2.0, .NET 8 and .NET 10 assets. It has no dependencies on other Kombine packages or projects and contains no database access, KID calculation or business rules. NuGet publication is controlled independently by the public SDK repository. This prepared release includes the 0.38.0 archive; use the local installation below if that version is not listed on NuGet.org.
Platforms and dependencies
Consumer platform
Client asset selected by NuGet
Dependencies
.NET Framework 4.7.2 / 4.8 / 4.8.1
.NET Standard 2.0
Microsoft System.Text.Json 10.0.12 and its Microsoft dependencies
.NET 8 / 9
.NET 8
No additional packages
.NET 10
.NET 10
No additional packages
Checks cover builds against Framework 4.7.2 and 4.8, running on installed Framework 4.8.1, plus execution on .NET 8, 9 and 10. An original 4.7.2 installation and older .NET Core/.NET versions have not been exercised. Microsoft recommends Framework 4.7.2 or later for .NET Standard. Customers without NuGet can still use the separate DLL packages for 2.0, 4.5 and CE/Mobile.
First select the tenant API URL, then enter e-mail and password. The client uses existing API operations; API functionality and permission enforcement are unchanged.
Installation
NuGet publication is controlled independently by the public SDK repository. This prepared release includes the 0.38.0 archive; use the local installation below if that version is not listed on NuGet.org.
Keep nuget.org or your approved mirror enabled to restore Microsoft dependencies. In Visual Studio, add the same local directory as a NuGet source. Framework executables should enable automatic binding redirects when dependency versions conflict; applications injecting their own HttpClient also need the framework System.Net.Http reference.
Login and tabs
using Kombine.Flex.Portal.Client;
// Inside an async method; tenantApiUrl ends in /
using (var api = new PortalApiClient(new Uri(tenantApiUrl)))
{
await api.LoginAsync(email, password, cancellationToken);
var manager = await api.GetCurrentManagerAsync(cancellationToken);
if (manager.TabDetails != null)
foreach (var tab in manager.TabDetails)
Console.WriteLine($"{tab.Id}: {tab.Name}");
api.ClearSession();
}
Methods follow OperationIdAsync with typed request/response models and IntelliSense: for example, GetBankUsersAsync, GetBankUserBalancesAsync and GetInstallersAsync. Send canonical KIDs and cursors unchanged. The client grants no additional permissions and performs no automatic retries.
PortalApiException.StatusCode and Code describe API failures: 401 requires login, 403 denies access, 409 requires reloading the revision, 429 requires respecting Retry-After, and 503 means temporarily unavailable. Network failures use HttpRequestException. Never indiscriminately log passwords, tokens or entire responses.
ClearSession forgets the client's token; packaged clients do not renew automatically, and the API has no server-side logout operation. Switching tenant requires a new client and separate login. The separate console and Windows examples use only this client for API access. The Windows example displays permitted tabs and stores only token/expiry in Windows Credential Locker.
API contract changelog · Review request/response changes before updating your integration.
Python
Python 3.11+ · pip / wheel · 235 API-operations
kombine-flex-portal-client is a standalone Python 3.11+ package using only the standard library. No .NET, NuGet or other Kombine packages are needed.
Installation
Install the supplied wheel file locally. The package is not yet published to PyPI.
First select the tenant API URL ending in /, then email and password. Create a new client when switching tenants. The API enforces account, Tab, KID and operation permissions for every call. See access rules and error codes.
# Python: tenant_api_url, email and password come from your login form.
from kombine_flex_portal import PortalClient, PortalApiError
with PortalClient(tenant_api_url) as api:
try:
api.login(email, password)
manager = api.get_current_manager()
for tab in manager.get("tabDetails") or []:
print(tab.get("id"), tab.get("name"))
except PortalApiError as error:
print(error.status, error.code)
login() retains the token in memory. The raw login_manager(body) call does not retain a session. clear_session() and close() forget the local token; the API does not yet provide refresh or token revocation. Public calls never send the token. The client does not retain the password.
Operations and data types
All 235 operations have snake_case methods, such as get_bank_user_balances and get_installers. Request and response models are TypedDict in kombine_flex_portal.models. JSON field names, KIDs, cursors and revisions are preserved. Int64 uses exact Python integers; ISO dates remain strings. Null is not zero.
with api.export_bank_users(bank_kid) as download:
with open("residents.csv", "wb") as target:
for chunk in download.iter_bytes():
target.write(chunk)
PortalApiError exposes status, code, headers and response. The response may contain personal data. Network failures use URLError/OSError/TimeoutError; invalid or oversized JSON raises PortalProtocolError. No automatic retries or pagination.
The client is synchronous. The default timeout=30 is a socket I/O timeout, not an overall deadline for a long download. JSON defaults to a 16 MiB limit. Use a worker thread in async/GUI applications. HTTPS uses normal certificate validation; redirects are refused.
API contract changelog · Review request/response changes before updating your integration.
@kombine/flex-portal-client is one ESM package containing JavaScript and TypeScript declarations. It works in Node.js 22+ and modern browsers with fetch, BigInt and Web Streams. There are no runtime dependencies or other Kombine packages.
Installation
Install the supplied tarball. The package is not yet published to npm. TypeScript is optional; compiled JavaScript is already included.
First select the tenant API URL ending in /, then email and password. Create a new client when switching tenants. The API enforces account, Tab, KID and operation permissions for every call. See access rules and error codes.
import { PortalClient, PortalApiError } from '@kombine/flex-portal-client';
const api = new PortalClient(tenantApiUrl);
try {
await api.login(email, password);
const manager = await api.getCurrentManager();
for (const tab of manager.tabDetails ?? []) console.log(tab.id, tab.name);
} catch (error) {
if (error instanceof PortalApiError) console.error(error.status, error.code);
else console.error('The API request could not be completed.');
} finally { api.clearSession(); }
login() retains the token in memory. The raw loginManager(body) call does not retain a session. clearSession() and close() forget the local token; the API does not yet provide refresh or token revocation. Public calls never send the token. The client does not retain the password.
Operations and data types
All 235 operations have camelCase methods and exported TypeScript interfaces. Int64 fields use bigint, including expiresIn, so large balances are not rounded. Int32 uses number; dates remain ISO strings. KIDs, cursors, revisions and null are preserved.
Use value.toString() to display bigint. JavaScript JSON.stringify cannot directly handle bigint; explicitly choose a representation such as strings for your own JSON output. The client serializer sends int64 correctly as JSON numbers. Do not blindly convert large amounts to Number.
PortalApiError exposes status, code, headers and response; entire responses may contain personal data. Network/CORS failures use fetch errors, cancellation/timeouts normally use AbortError/TimeoutError, and invalid JSON raises PortalProtocolError. No automatic retries or pagination.
The default timeoutMs: 30_000 covers the entire response, including streaming. Each call accepts AbortSignal. JSON defaults to a 16 MiB limit; file downloads are streamed and must be closed. HTTPS uses normal certificate validation, and redirects are refused.
Browser / CORS
Use a bundler, or host the entire package dist directory on your webserver and import ./dist/index.js from a <script type="module">. The API Cors:AllowedOrigins must allow the page’s exact origin. Browsers can only read CORS-exposed response headers. Node.js does not require browser CORS.
Customers with legacy .NET Framework 2.0 applications can reference Kombine.Flex.Portal.Client.Net20.dll using Add Reference → Browse. The ZIP includes the DLL, XML IntelliSense documentation, source, Kombine.Flex.Portal.Client.2008.sln and a standalone test application. No NuGet or Kombine packages are needed; only mscorlib 2.0 and System 2.0. This targets .NET Framework 2.0, not .NET Standard 2.0.
Installation
Extract the ZIP and add the client DLL using Add Reference → Browse. Keep the supplied XML file beside the DLL for IntelliSense. NuGet is not required.
Login and tabs
Place using/Imports directives at the top of the file and the remaining code inside a method. Input variables (tenantApiUrl, credentials and KIDs) come from your application. The examples use the same DLL in both languages.
C#
using System;
using Kombine.Flex.Portal.Client.Net20;
using (PortalApiClient api = new PortalApiClient(new Uri(tenantApiUrl)))
{
ManagerSessionResponse session = api.Login(email, password);
ManagerProfileResponse manager = api.GetCurrentManager();
Console.WriteLine(manager.Name);
if (manager.TabDetails != null)
{
foreach (ManagerTabResponse tab in manager.TabDetails)
Console.WriteLine("{0}: {1}", tab.Id, tab.Name);
}
api.ClearSession();
}
VB.NET
Imports System
Imports Kombine.Flex.Portal.Client.Net20
Using api As New PortalApiClient(New Uri(tenantApiUrl))
Dim session As ManagerSessionResponse = api.Login(email, password)
Dim manager As ManagerProfileResponse = api.GetCurrentManager()
Console.WriteLine(manager.Name)
If manager.TabDetails IsNot Nothing Then
For Each tab As ManagerTabResponse In manager.TabDetails
Console.WriteLine("{0}: {1}", tab.Id, tab.Name)
Next
End If
api.ClearSession()
End Using
Select the tenant API URL first. All 235 public integration operations have synchronous methods without an Async suffix. Optional filters use OperationOptions classes, such as GetBankUsersOptions. Dates/timestamps are ISO 8601 strings preserving offsets; money in minor units uses nullable Int64. Keep KIDs/cursors/revisions unchanged. The library contains no database access or business rules.
API errors use PortalApiException with StatusCode, Code and Headers; follow the same 400/401/403/404/409/429/503 rules described above. Network/TLS/timeouts use WebException. There are no automatic retries. Calls block and should run on a background thread in desktop UIs. ClearSession forgets the local token; use RenewManagerSession explicitly for renewal; individual token revocation is unavailable.
HTTPS requirements: .NET 2.0-compatible code still needs a patched Windows/CLR 2.0 installation supporting TLS 1.2 and trusted certificates. The library does not change machine settings. Explicitly calling PortalApiClient.EnableTls12() selects TLS 1.2 for the entire host process and fails if unsupported. See Microsoft's TLS guidance. No fallback disables certificate validation or sends customer data over insecure HTTP.
API contract changelog · Review request/response changes before updating your integration.
Kombine.Flex.Portal.Client.Net45.dll exposes the same 235 typed synchronous API operations. The ZIP includes DLL/XML, source, Kombine.Flex.Portal.Client.2012.sln and a standalone test application. Only framework libraries are required; no NuGet or Kombine dependencies. VS2008 supports up to .NET Framework 3.5; 4.5 requires VS2012 or compatible build tools. See Microsoft's version overview.
Installation
Extract the ZIP and add the client DLL using Add Reference → Browse. Keep the supplied XML file beside the DLL for IntelliSense. NuGet is not required.
Login and tabs
Place using/Imports directives at the top of the file and the remaining code inside a method. Input variables (tenantApiUrl, credentials and KIDs) come from your application. The examples use the same DLL in both languages.
C#
using System;
using Kombine.Flex.Portal.Client.Net45;
using (PortalApiClient api = new PortalApiClient(new Uri(tenantApiUrl)))
{
ManagerSessionResponse session = api.Login(email, password);
ManagerProfileResponse manager = api.GetCurrentManager();
Console.WriteLine(manager.Name);
if (manager.TabDetails != null)
{
foreach (ManagerTabResponse tab in manager.TabDetails)
Console.WriteLine("{0}: {1}", tab.Id, tab.Name);
}
api.ClearSession();
}
VB.NET
Imports System
Imports Kombine.Flex.Portal.Client.Net45
Using api As New PortalApiClient(New Uri(tenantApiUrl))
Dim session As ManagerSessionResponse = api.Login(email, password)
Dim manager As ManagerProfileResponse = api.GetCurrentManager()
Console.WriteLine(manager.Name)
If manager.TabDetails IsNot Nothing Then
For Each tab As ManagerTabResponse In manager.TabDetails
Console.WriteLine("{0}: {1}", tab.Id, tab.Name)
Next
End If
api.ClearSession()
End Using
Select the tenant API URL before login. The same account/Tab/KID/operation permissions and error codes apply. PortalApiException exposes HTTP status, code and headers; network/TLS/timeout failures use WebException or I/O exceptions. Invalid/oversized JSON raises InvalidDataException. There are no automatic retries or token refresh. The JSON limit is 16 MiB; downloads are streamed and must be disposed. Dates remain ISO 8601 strings and balances nullable Int64. The explicit TLS helper changes process-wide protocol selection, not certificate checks or the registry. Builds are checked against 4.5 reference assemblies; runtime checks use a newer installed CLR 4, not an original 4.5 installation.
API contract changelog · Review request/response changes before updating your integration.
Windows CE / Windows Mobile: Compact Framework 2.0
Use Kombine.Flex.Portal.Client.Compact20.dll in Smart Device projects. The separate Kombine.Flex.Portal.Client.Compact2008.sln and ZIP include all 235 typed synchronous operations, source and an on-device test application. Only Compact Framework libraries are required; no NuGet or Kombine dependencies. The desktop client DLL is not a substitute.
Installation
Extract the ZIP and add the client DLL using Add Reference → Browse. Keep the supplied XML file beside the DLL for IntelliSense. NuGet is not required.
Login and tabs
Place using/Imports directives at the top of the file and the remaining code inside a method. Input variables (tenantApiUrl, credentials and KIDs) come from your application. The examples use the same DLL in both languages.
C#
using System;
using Kombine.Flex.Portal.Client.Compact20;
using (PortalApiClient api = new PortalApiClient(new Uri(tenantApiUrl)))
{
api.TimeoutMilliseconds = 30000;
ApiStatusResponse status = api.GetPortalStatus();
ManagerSessionResponse session = api.Login(email, password);
ManagerProfileResponse manager = api.GetCurrentManager();
Console.WriteLine(manager.Name);
if (manager.TabDetails != null)
{
foreach (ManagerTabResponse tab in manager.TabDetails)
Console.WriteLine("{0}: {1}", tab.Id, tab.Name);
}
api.ClearSession();
}
VB.NET
Imports System
Imports Kombine.Flex.Portal.Client.Compact20
Using api As New PortalApiClient(New Uri(tenantApiUrl))
api.TimeoutMilliseconds = 30000
Dim status As ApiStatusResponse = api.GetPortalStatus()
Dim session As ManagerSessionResponse = api.Login(email, password)
Dim manager As ManagerProfileResponse = api.GetCurrentManager()
Console.WriteLine(manager.Name)
If manager.TabDetails IsNot Nothing Then
For Each tab As ManagerTabResponse In manager.TabDetails
Console.WriteLine("{0}: {1}", tab.Id, tab.Name)
Next
End If
api.ClearSession()
End Using
Select the tenant HTTPS API URL first. Login, tabs, KIDs and operation permissions follow the rules above. API errors use PortalApiException; network failures use WebException or I/O exceptions. Invalid/oversized JSON raises PortalProtocolException. The JSON limit is 2 MiB; use small pages. Downloads are streamed. The overall HTTP deadline defaults to 30 seconds and is configurable. There are no automatic retries or token refresh.
Device requirements: CF 2.0 compatibility does not guarantee modern HTTPS. TLS, cipher suites and certificate support depend on the device OS/OEM image. There is no EnableTls12() in the Compact client, and it does not upgrade the networking stack. Test GetPortalStatus() on the actual device before login. No insecure fallback or changes to API security are made. The library and device tests build against CF 2.0; runtime/HTTPS on a physical CE/Mobile device or emulator has not yet been verified.
Source package 0.30.0 includes 235 operations from the bundled contract, examples, synthetic tests and English, Danish and Spanish READMEs. Requires Dart 3.6 or later (below 4.0). Extract beside your application and add this path dependency:
Use the tenant API URL and manager credentials supplied by your application. Object models use wire-map fields; int64 values use BigInt. HTTPS and normal API permissions apply. No automatic retries. Flutter device execution has not been tested. This package is not published to pub.dev.
64-bit PHP 8.2+, ext-curl and ext-json. No additional PHP libraries. Version 0.35.0 is included in the API downloads. It is not published to Packagist.
Version 0.3.1 synchronizes GetBankUserBalances documentation with its 20-second database deadline. Request and response fields are unchanged. Allow extra time for transport and authorization; HTTP 503 still returns no partial balances. Version 0.2.5 adds optional latestPostingMs2000 and hasActiveSubscription fields to GetBankUserBalances. The posting time is a 64-bit UTC millisecond count since 2000-01-01; zero means no postings. Null or an absent field means unknown, and missing or hidden residents return null. Subscription status is not payment confirmation. Keep existing balance handling and permissions; see /docs#user-balances. Version 0.2.5 adds GetLocationOpeningHours and GetLocationBookingRules. Both require Location Read, Unit Read and the authorized location scope. Reservation rules contain plain text plus ordered parts with text/isValue for optional value emphasis; never render these strings as HTML. Keep text as the fallback for older responses. See /docs#location-opening-hours and /docs#location-booking-rules for permissions, examples and limits. Version 0.2.5 adds GetUserReceipts and GetHostingMetrics for API releases that expose these operations. Load receipts on demand, starting at offset 0. Continue with nextOffset and the same revision; on HTTP 409 (receipts-changed), discard earlier pages and restart at offset 0. Keep currencies separate and minor-unit amounts as 64-bit integers. See /docs#user-receipts and /docs#hosting for permissions and limits.
Without Composer: extract to flex-portal-client/ and require its autoload.php instead. Keep the complete src/ folder. The ZIP includes English, Danish and Spanish READMEs, operation and model references, and the public OpenAPI snapshot.
Use a manager email and password for the tenant Portal API. Supply tenantUrl and the login variables from protected application configuration or a login form. The API URL must end with /. Keep the bearer on the PHP server.
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use Kombine\Flex\Portal\PortalClient;
use Kombine\Flex\Portal\ApiException;
use Kombine\Flex\Portal\ProtocolException;
use Kombine\Flex\Portal\TransportException;
$api = new PortalClient($tenantUrl, timeout: 30);
try {
$session = $api->login($email, $password);
$result = $api->getCurrentManager();
} catch (ApiException $error) {
$status = $error->status;
$code = $error->apiCode;
$retryAfter = $error->headers['retry-after'] ?? null;
// Handle according to the table below; do not blindly repeat writes.
} catch (TransportException | ProtocolException $error) {
// Timeout, network failure, malformed data or response limit.
// A write may already have completed: check state before repeating it.
} finally {
$api->close();
}
renew() explicitly calls RenewManagerSession and stores the replacement token. Raw renewManagerSession() only returns the response. Renew while the bearer is unexpired, based on user activity; after expiry or revocation, log in again. There is no separate refresh token.
Every business call still requires the manager’s account state, permitted Tab, KID scope and operation permission. A KID itself grants no access.
Paging is explicit: keep the returned cursor and continue until it is absent, including after an empty page. Keep revision tokens for writes. Use a temporary file for downloads and rename it only after success.
$page = $api->getBankUsers($bankKid, ['pageSize' => 25, 'sort' => 'number']);
$balances = $api->getBankUserBalances($bankKid, ['userKids' => $userKids]);
$receipts = $api->getUserReceipts($userKid, ['offset' => 0]);
// Request the next page only when needed, using nextOffset and the same revision.
$stream = fopen($temporaryPath, 'w+b');
try {
$download = $api->exportBankUsers($bankKid, $stream);
} finally {
fclose($stream);
}
rename($temporaryPath, $completedPath);
ApiException exposes status, apiCode and lowercase headers. 400: correct input; 401: sign in; 403: check permissions; 404/409: reload and resolve conflicts; 429: respect Retry-After; 5xx: handle temporary failure. TransportException and ProtocolException mean network/deadline or invalid/oversized data. A failed write may have completed: check state before retrying. Never log credentials, tokens or complete payloads.
Responses use associative arrays; lists use indexed arrays. Use native 64-bit int for integer fields; preserve missing/null values. The client verifies TLS, refuses redirects, omits tokens on anonymous calls and clears the session on HTTP 401. Default limits: 30 seconds total, 16 MiB JSON, 64 KiB headers, 1 GiB per download. Downloads write to a caller-owned stream; discard partial files on failure. No automatic retries, paging, renewal or acknowledgements. Server-side PHP does not need browser CORS.
Unit directory (Units1)
Running units (locally implemented, unreleased):GET /api/v1/units?runningOnly=true&fields=progress&sort=progress&direction=asc filters before sorting and pagination. A running unit has valid positive Log24 Started/Done timestamps with start <= calculation time < expected end. Missing, invalid, future-start and completed timing is excluded. Default is false; selecting progress is optional. Combine with enabledOnly, search and authorized location/terminal scope. No additional device-state or machine-type filter is applied. Calculation time stays fixed across nextCursor pages for at most 15 minutes; refresh the first page for current running units. Repeat runningOnly with every cursor; changing it returns 400 invalid-cursor. GetTerminals rejects runningOnly=true with 400 invalid-filter. Existing Units1, Bank/Location/Unit Read, resource scope, retention and 401/403/503 behavior remain unchanged.
Optional progress (locally implemented, unreleased):GET /api/v1/units?fields=progress adds items[].progress: {status,percent,remainingSeconds,calculatedAtUtc}, using exactly the overview-card calculation. It reads lifecycle inputs in one bounded Log24 query for the authorized page and calculates at request time. The percentage uses only the start and expected end times, clamped to 0–100. Missing or invalid times give null percent. Without selection, progress is null. GetTerminals does not populate it. Use sort=progress with direction=asc/desc for numeric sorting before pagination (GetUnits only). Unknown values sort first ascending and last descending. The calculation time is fixed across each cursor chain for at most 15 minutes, so time passing alone cannot move units between pages; device updates can still move rows. Permissions and retention are rechecked at the current time. Progress cannot be searched; preserve fields with nextCursor. Existing Units1, Bank/Location/Unit Read, scope and RetentionDays checks and 400/401/403/503 responses apply. The value is a snapshot, not a live update.
GetUnits additionally accepts terminalKid: GET /api/v1/units?terminalKid={controllerKid}. The parameter is a canonical Controller KID with MainId (UnitId=0). Returns the first unit and child units mapped by same-location Alive.MainId to that controller. The parent must be a retention-visible, authorized Log24 unit; contradictory mappings, chains and cycles do not qualify. A missing parent Alive row is allowed, but missing child mappings never infer membership. Existing Units1 and Bank/Location/Unit Read checks apply. Filtering precedes pagination. Repeat terminalKid with every cursor; changed options return 400 invalid-cursor. Invalid/wrong-tenant KIDs and terminalKid on GetTerminals return 400 invalid-terminal. Omit it for the existing directory. Locally implemented, unreleased.
Optional locationKid on GetTerminals and GetUnits restricts the directory to one canonical location KID in the site tenant. It intersects existing grants before search, sorting and pagination; authorization and terminal classification are unchanged. Example: GET /api/v1/terminals?locationKid={locationKid}&enabledOnly=true. Repeat it unchanged with each cursor; a changed scope returns 400 invalid-cursor. Invalid or wrong-tenant KIDs return 400 invalid-location. Omit it for the cross-location directory. Implemented locally, unreleased.
Unreleased: sort=kid orders GetUnits and GetTerminals numerically by bank, location and unit within the trusted tenant. Use direction=asc or desc; keep both options unchanged when following a cursor.
Unreleased: fields=machineType,machineProgramSet,currentVersion on GetUnits includes decoded stored eSetting.MashineType, eSetting.MashineProgramSet and eSetting.CurrentVersion for the exact unit as strings. Absent or unselected fields are omitted; no values are inferred. Keep fields unchanged when following a cursor. These fields are not available on GetTerminals.
GetUnits — GET /api/v1/units
Requires an active manager with Units1 (50), Bank Read, Location Read, Unit Read and matching resource grants. Includes main and child units discovered in the trusted tenant’s Log24. Limited grants require an enabled parent location and retained bank/location/unit deletion states; site-wide grants may inspect all states. enabledOnly=true narrows the result to units with Enabled exactly 1.
Use fields=locationName,bankName,unitType,washDocId,outOfOrder for optional columns. Core canonical kid, locationKid, bankKid, names, iconKids and enabled/deleted/deletedAt are always returned. Optional unit values are null unless selected and empty when absent. Type comes only from original packed UnitType using (value >> 1) & 255; UnitType2 is ignored, including as a fallback. includeCoordinates=true returns parent-location latitude/longitude in decimal degrees; missing/invalid coordinates are null.
filter searches stored names, unit numbers/types, WashDocId and OutOfOrder, or an exact canonical/site-relative bank, location or unit KID. sort accepts kid, name, bankName, locationName, unitId, unitType, washDocId or outOfOrder; direction=asc/desc. Unit number/type and WashDocId sort numerically; text uses utf8mb4_general_ci. Display names can be localized; search/order use stored names.
pageSize is 1–250 (default 50). Repeat the same options and bearer session with nextCursor until null. Cursors expire after 15 minutes and bind tenant, manager, grants, retention and query options. Restart without a cursor when changing options. Concurrent edits can move rows.
400 invalid-page/filter/sort/fields/cursor: correct input or restart paging. 401: sign in again. 403 missing-units-tab/missing-bank-read/missing-location-read/missing-unit-read/missing-resource-access: review permissions. 503 units-unavailable: retry manually. No-store. Included in this host release and clients 0.16.0.
GET /api/v1/units?pageSize=50&fields=locationName,bankName,unitType&enabledOnly=true&sort=name&direction=asc
Authorization: Bearer <session-token>
Active unit count
GetActiveUnitCount — GET /api/v1/units/active-count returns {count,iconKid} for the Units1 navigation badge. Reuse the manager bearer session. It requires the same active manager, Units1 (50), Bank Read, Location Read, Unit Read and matching site/bank/location grants as GetUnits. Counts distinct Log24-discovered main and child units with Enabled exactly 1 and Deleted zero or absent; malformed deletion values and deleted units are excluded, including for site-wide grants. Limited grants still require an enabled parent location and bank/location deletion states visible under RetentionDays; site-wide grants bypass only those parent-state restrictions. The trusted site fixes the tenant.
The count is independent of search, selected columns, sorting and paging; no directory query parameters are needed. iconKid is the complete icon identity with its count badge: render it unchanged through the icon API instead of composing a badge identity. It grants no access. Counts are read afresh; permission snapshots may be up to 60 seconds old. Responses are no-store. 401: sign in again. 403 missing-units-tab, missing-bank-read, missing-location-read, missing-unit-read or missing-resource-access: review permissions. 503 units-unavailable means storage is unavailable or the 12-second deadline expired: allow manual retry and never display the failure as zero. The portal loads the count in the background as it does for Locations, with the full count in the icon badge and localized help. Implemented locally, not yet released; generated clients and download packages will be synchronized at beta deployment.
Terminal directory (unreleased):GetTerminals (GET /api/v1/terminals) returns name from eState.ComputerName, not eSetting.Name. Name filtering/sorting follows ComputerName; missing names are empty. Request additional decoded string columns with ?fields=versionMinor,bootReason,booted,firmware,storageCardSerialNumber,page,backLight. Booted uses eSetting.Booted; the others use eState. Unselected fields are null; selected missing values are empty. These fields can also be used as sort values (text ordering). Keep fields and sort unchanged when following nextCursor. Terminals1 and Bank/Location/Unit Read plus bounded resource grants remain required; invalid fields/sorts return 400, missing permissions 403. This does not change GetUnits.
Each row's iconKid uses the fixed terminal icon, independent of eSetting.Icon, with UnitId in its Text field. Render it unchanged; do not replace it with the lazy unit-icon response.
GetTerminals — GET /api/v1/terminals returns the same UnitDirectoryResponse shape as GetUnits: {items,nextCursor,hasAllBanksAccess,fields}. Requires an active manager with Terminals1 (66), Bank Read, Location Read, Unit Read and matching site/bank/location grants. Terminals1 is checked independently; Units1 is not required. Every page rechecks permissions and RetentionDays. Limited grants require an enabled parent location and retained bank/location/unit deletion states; an explicit site-wide grant may inspect all states.
Only Log24-discovered units whose UnitId equals a positive Alive.MainId at the same bank and location are returned. Several Alive rows may refer to one main terminal; it appears once. An Alive child row can identify its main terminal but is not itself a terminal result. Missing/zero MainId, orphan Alive identities and unauthorized units are excluded. This is a read-only classification from the trusted tenant's Alive table; it does not discover extra equipment, report online status or grant access. GetUnits continues to include main and child units.
Use the same query options as GetUnits: fields=locationName,bankName,unitType,washDocId,outOfOrder, filter, sort=kid|name|bankName|locationName|unitId|unitType|washDocId|outOfOrder, direction=asc|desc, enabledOnly, includeCoordinates, pageSize and cursor. Core canonical KIDs, names, iconKids and enabled/deleted/deletedAt remain populated; unselected optional unit fields are null and selected missing values are empty. Type comes only from original packed UnitType using (value >> 1) & 255; UnitType2 is ignored, including as a fallback. A filter of at most 128 characters searches stored names, unit numbers/types, WashDocId and OutOfOrder or an exact canonical/site-relative bank, location or unit KID. Display names may be localized; search/order use stored values. Numeric unit/type/WashDocId ordering and text comparison match GetUnits. enabledOnly=true requires Enabled exactly 1. includeCoordinates=true returns the parent location's nullable decimal-degree coordinates for maps; follow every page to collect the complete authorized map.
pageSize is 1–250, default 50. Reuse the manager bearer session and repeat unchanged query options except pageSize with nextCursor as cursor until it is null. Keyset cursors expire after 15 minutes and bind the directory, tenant, manager, grants, retention and options. Restart without a cursor after changing them; a GetUnits cursor cannot be used for GetTerminals. Concurrent edits or Alive changes may move rows.
Replace the HTTPS origin with your tenant's Portal API and reuse a valid manager token:
400 invalid-page, invalid-filter, invalid-sort, invalid-fields or invalid-cursor: correct input or restart paging. 401: sign in again. 403 missing-terminals-tab, missing-bank-read, missing-location-read, missing-unit-read or missing-resource-access: review permissions. 503 terminals-unavailable: show the failure and allow manual retry; do not treat it as an empty directory. Responses are no-store. Implemented locally, not yet released; generated clients and download packages will be synchronized at beta deployment.
Active terminal count
GetActiveTerminalCount — GET /api/v1/terminals/active-count returns {count,iconKid} for the Terminals1 navigation badge. It requires the same active manager, Terminals1 (66), Bank Read, Location Read, Unit Read and matching site/bank/location grants as GetTerminals; Units1 is not required. Active-state and parent-visibility rules match GetActiveUnitCount. Only authorized Log24-discovered units whose UnitId matches a positive tenant-bound Alive.MainId at the same bank and location contribute. Each terminal identity counts once, even when multiple child Alive rows identify it; those children are not extra terminals.
Reuse the manager bearer session; no search, column, sort or paging parameters are needed. Render the returned iconKid unchanged through the icon API; it grants no access. The count is read afresh with no-store responses, independently of directory filters. 401: sign in again. 403 missing-terminals-tab, missing-bank-read, missing-location-read, missing-unit-read or missing-resource-access: review permissions. 503 terminals-unavailable means storage is unavailable or the 12-second deadline expired: allow manual retry and never display the failure as zero. The portal loads the badge in the background as it does for Locations. Implemented locally, not yet released; generated clients and download packages will be synchronized at beta deployment.
GetUnitDocumentCycleInfo (GET /api/v1/documents/{cycleKid}/cycle-info) previously returned only scalar machineType per entry. The prepared response also includes unitType, machineProgramSet, version and up to 128 numeric values represented as strings to preserve precision. Clients should tolerate missing metadata and parse value strings as 64-bit integers. Other CycleInfo fields remain redacted. Regenerated client downloads cover 234 public operations and use this contract. Release status depends on the selected environment.
Unreleased · 2026-11-03
LiveWashBubbles and 15-second running-list refresh
Wallboard widget 55 uses Matter.js and the complete public running-units list. Bubbles are keyed by unitKid, born at startedAtUtc plus 15 seconds, grow with delayed progress and disappear after confirmed removal. The existing array contract is unchanged. The list cache and failure backoff are now 15 seconds; the optional X-Portal-Refresh-After-Ms response header aligns clients with cache expiry. Hidden widgets pause; reduced motion is respected.
Unreleased · 2026-11-03
GetPublicRunningMachineList — complete running list without temperature
GET /api/v1/public/statistics/running-units returns all matching machines without temperature or paging. Responses include nullable unitType and cycle. The existing running interval remains unchanged. The existing live-machines endpoint remains unchanged; storage limits return 503 rather than a partial list.
Superseded · earlier Team beta candidate
Updated client downloads
The earlier Team beta client candidate covered 233 public operations, including running units. Package versions differ by client: .NET 0.35.0, Python 0.39.0, JavaScript 0.38.0, Dart 0.27.0, legacy .NET 0.34.0 and PHP 0.33.0. The entries below record earlier releases.
Unreleased
Screen sessions expire after one hour
Newly redeemed and resumed Wallboard screen sessions return expiresIn: 3600. Screen approval remains durable: on expiry, clients obtain a new session using a signed device challenge. Existing bearer tokens retain their original expiry. Ordinary manager session duration is unchanged.
Prepared for Team beta · deployment status tracked by the environment
Consolidated Portal and Wallboard contract: clients 0.31.0, Dart 0.22.0
The downloadable clients cover 231 operations, including atomic public/private Wallboard page transfers, revision polling for Overview and current widget types. Account reads default to today with no upper date limit: an omitted through now returns null, and entries are ordered from oldest to newest. Consumers must handle the nullable end date; an explicit end date retains the bounded date-range rules. Existing authorization, tenant isolation and revision checks remain in force.
All client variants and their downloadable archives are synchronized. Historical versioned downloads remain available. This release does not publish packages to registries or update other tenants, production, Equipment, Jobs or the standalone Wallboard app.
Team beta deployed · other tenants and production pending
Team beta Web and Portal API share dedicated regional hosts
Team beta now runs on dedicated Frankfurt and Amsterdam installations behind its existing Bunny load balancer. The public Web and API URLs, API contracts, permissions and tenant binding are unchanged. WebSocket affinity and new connections after either region is disabled have been verified; an existing browser session may need to reconnect or reload during an interruption. This rollout does not update other tenants, Equipment, Jobs or standalone Wallboard, and performs no stored-data migration.
Unreleased · beta/production pending
Protected manager activity and application load widgets
Managers with Wallboards, Managers Read and whole-tenant access can view the aggregate of active managers. Team managers with Hosting access can view configured production application CPU and memory history. Approved displays are bound to their saved widget types. Beta reads previously recorded activity without writing activity on login or renewal; production records interactive activity. Public wallboards cannot publish these widgets.
Unreleased · beta/production pending
Revenue heatmaps use the wallboard map provider
When the tenant enables MapTiler for wallboards, revenue heatmaps use the same transparent map as purchase and location widgets. Revenue points are rendered locally; if the configured provider is unavailable, the widget does not silently switch providers. Other portal maps retain their existing provider.
Unreleased · beta/production pending
Private Plex playback for wallboards
Authorized managers can search the configured Kombine Plex Home profile and select a video or playlist. Approved screens can play only references saved in their display layout. Stream tickets remain bound to the tenant and current manager or screen authorization; Plex credentials remain on the API host. Public wallboards cannot publish Plex widgets. Client downloads include the search, queue, playback, stream and stop operations.
Unreleased · beta/production pending
Wallboard background colors use light and dark palettes
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards, GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId}, GetPublicWallboardEditor — GET /api/v1/session/me/wallboards/public, SavePublicWallboardEditor — PUT /api/v1/session/me/wallboards/public and GetPublicWallboard — GET /api/v1/public/wallboard change layout c from one array of unsigned color values to two arrays of signed 32-bit values, ordered light then dark. Stored legacy single palettes are converted in memory to both palettes while retaining each 32-bit pattern; reading does not write stored settings.
Migration: read and write two arrays, for example "c":[[1122867],[4478310]], and send "c":[[],[]] to clear both. Preserve 32-bit color patterns when converting previously unsigned values. Keep revision, authorization and existing screen IDs unchanged.
Team beta · rollout status depends on the environment
Account2 starts at one date and reads oldest postings first
GetBankAccount — GET /api/v1/banks/{bankKid}/account, GetBankAccountRevision — GET /api/v1/banks/{bankKid}/account/revision and ExportBankAccount — GET /api/v1/banks/{bankKid}/account/export now interpret omitted through as no upper date boundary, instead of defaulting it to today. The account response's through is now nullable. An explicit through remains inclusive and bounded to 367 dates. from still defaults to local today; an explicit settlement period still replaces the date filter.
Rows and exports now sort by MS2000 ascending, then location/unit, instead of newest first. The documents array also orders its groups oldest first. Migration: accept nullable through, supply it explicitly if a bounded interval is required, discard cached pages when changing release/order, and append newer entries with increasing offsets. Compare full-selection revisions and reconcile the loaded prefix on late arrivals. Authorization, signed amounts, currency totals, retention and existing page/export/time limits remain in place. Packaged clients for the consolidated Team beta contract are available.
Unreleased · alfa verification only
Symbol-only and text-only logo widgets
LogoMark (43) and LogoWordmark (44) are selectable in the editor and render in previews, approved screens and public wallboards. GetPublicWidgetPresentation adds nullable BrandLogoMarkUrl, BrandDarkLogoMarkUrl, BrandLogoWordmarkUrl and BrandDarkLogoWordmarkUrl from the trusted tenant's validated branding profile. Missing variants have no cross-tenant or full-logo fallback. Widgets retain their proportions, have no background and use the container theme. Only empty/style-only KIDs are accepted; layout geometry, authorization and revision checks are unchanged.
Unreleased · alfa verification only
Reservation calendar hides machines without bookings in the next day
The wallboard renderer now shows only machines with an ongoing reservation or one beginning within the next rolling 24 local wall-clock hours. Row selection refreshes automatically and preserves source order and unknown schedule periods. The six-hour guide advances using these displayed machines, and an empty result has a localized message. The existing authorized two-day response, API contracts, data reads and permissions are unchanged.
Unreleased · beta/production pending
Video search uses provider or AI web results without a shared catalogue
SearchMyWallboardVideos — GET /api/v1/session/me/wallboards/videos/search now returns source:provider for YouTube (39) or source:web for Vimeo (40), Wistia (41) and Mux (45). The former catalog source, fixed shared lists and catalogue fallback are removed. Real queries use the tenant's explicitly enabled integration. Web results include items[].sourceUrl, an observed HTTPS source/citation URL; YouTube retains its id/name shape without that field. Sources may be public publisher pages containing embeds. No account inventory, manager token, layout data, business tools or conversation history is sent to search.
Migration: support provider|web and remove fixed-list behavior. Show visible clickable web citations beside titles; never infer an ID from a source URL, or save source URLs/titles in KIDs/layouts. Keep citation navigation separate from explicit selection, which still saves only the canonical reference through the revision-checked operation, preserving Vimeo hashes, theme and geometry. Empty/one-character queries now return empty results without external calls. Missing configuration and operational failures return 503 instead of a catalogue; limits return 429 with Retry-After. A completed search without eligible matches remains a successful empty result with its correct source. Search may take up to 35 seconds; preserve cancellation and drafts. Independent video metadata checks do not prove the AI's publisher/video association or guarantee embedding permission and continued playback. Authentication, Wallboard1 checks, query bounds and the maximum 20 results remain unchanged.
Unreleased · alfa verification only
LocationStatus begins with the location name
The fitted LocationStatus grid now places a name-only LocationInfo cell before every machine card, using the already public location name from the complete progress response. All machines remain included, and the name uses the shared top-left presentation in both themes. Standalone LocationInfo remains protected; no API response fields or authorization rules change.
Unreleased · alfa verification only
A stale wallboard challenge no longer invalidates device approval
ResumeWallboardSession — POST /api/v1/wallboard/devices/{deviceId}/session: a correctly signed challenge that expired, was consumed or was superseded now returns HTTP 200 with status: "retry" and no token, instead of status: "expired". This prevents concurrent reconnects from starting a new QR approval. Invalid signatures, missing devices and invalid manager credentials remain rejected.
Migration: handle retry by retaining the non-exportable device key and approved device ID, waiting briefly, requesting a fresh challenge and signing it. Do not replay the old proof or start QR pairing. The original approval, tenant/environment isolation, explicit revocation and fresh credential checks remain in force.
Team beta rollout 2026-11-01 · other tenants and production pending
Portal clients 0.24.0 and Dart 0.14.0 for the consolidated Wallboard contract
The reviewed client archives cover 217 API operations, including the eleven public-layout and protected widget-data operations described below. Regenerated models use ordered display ID arrays and rectangle arrays on the unchanged 60 by 60 grid. Rebuild callers that used the superseded scalar display ID or individual coordinate fields; preserve stored geometry and the separate authorized revisions for personal and public Portal wallboards. Screen-bound data access and tenant/resource permissions remain enforced by the API.
UserBalance's wire contract is unchanged. NuGet publication is independent of the server release; use the supplied, versioned download archives where the new version is not yet listed. Existing versioned downloads remain available. The consolidated release is deployed only to Team beta; other tenants and production retain their previous release.
Team beta rollout 2026-11-01 · other tenants and production pending
YouTube wallboard widgets use type 39 instead of Video type 26
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId}, including display reads with ?after=REVISION, now return t:39 (eWidgetType.YouTube) for the YouTube implementation previously returned as t:26 (eWidgetType.Video). This affects widgets inside both the physical wallboards collection and the separate portalWallboard. KID content and style, rectangles, page/widget order and playback behavior are unchanged.
Migration: clients must recognize and send t:39. Existing stored type 26 is converted in memory without database writes or a revision change; clients must process the returned layout even when its revision is unchanged. PUT still accepts legacy t:26 as an input alias, normalizes it before YouTube validation and writes canonical type 39 only through the existing authorized, revision-checked save. Unchanged older small widgets continue to match the freshly read stored inventory after the same normalization, without resizing or weakening distinct-widget checks. Video (26) is no longer separately selectable. The current release also implements Vimeo (40), Wistia (41) and LiveLocation (42), as described in the Wallboard integration guide. Routes, operation IDs, authorization, error statuses and concurrency checks are unchanged.
New or changed wallboard widgets require at least 3 by 3 cells
SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards uses Enums 2.0.151. Both size values in r: [x,y,width,height] must now be at least 3 instead of 1 for new or changed widgets. Previously stored smaller widgets may be retained unchanged: every submitted t/k/r must match a distinct stored widget after authorization and revision checks under the transaction lock. New, copied or changed smaller widgets return HTTP 400 invalid-wallboards without writing. An omitted r now defaults to [0,0,3,3] instead of [0,0,1,1]. The data grid remains 60 by 60, and bounds, overlap, supported widget types, scanned IDs, authorization and revision checks are unchanged.
Migration: send explicit rectangles and preserve unchanged older widgets when editing other parts of the collection. Resize a smaller widget to at least 3 on both axes before changing its type, KID or rectangle. GetMyManagerWallboards — GET /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} keep older stored dimensions, including the previous default for omitted rectangles, without writes or automatic resizing.
Wallboard orientation is replaced by an aspect ratio
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} replace layout p (0 landscape, 1 portrait) with positive finite a (width divided by height). The default is 16:9. Update clients to read and send a; use 16/9 for old landscape layouts and 9/16 for old portrait layouts. Stored older layouts are read without writes and converted on the next authorized save without changing widget coordinates. Permissions and revision checks are unchanged.
Wallboard display IDs and widget rectangles use arrays
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} use Enums 2.0.148. Layout i changes from a single string to an array of display IDs; widget x/y/w/h changes to r: [x,y,width,height]. Each ID must be unique in the collection and already scanned by that manager. A screen session receives only its own ID in i; a manager receives the complete array. Grid bounds, authorization and revision checks are unchanged.
Migration: update readers and writers to use these arrays and remove the four old rectangle properties. Stored older layouts remain readable and are converted on the next authorized save without rescaling. When combining displays with different saved backgrounds, supply explicit c to avoid an ambiguous legacy color merge.
New Wallboard pairings reject reserved display IDs
StartWallboardPairing — POST /api/v1/wallboard/pairings now rejects displayId values matching the standalone Wallboard host's application routes or root static asset filenames, case-insensitively, including compressed .gz/.br asset variants. Previously these names passed the general URL-segment validation and could create pairings whose standalone screen URL did not open a waiting page. Examples include api, swagger, health, wallboard-context.js and favicon.svg. Such new requests now return 400 instead of 200.
Migration: choose a different display ID before starting a new pairing. Existing stored layouts and approved devices retain their identities and normal credential, device-proof and revocation checks; this change performs no stored-data rewrite. Request/response field names and types are unchanged.
Verified on all five beta apps 2026-10-31 · clients 0.21.0 / Dart 0.11.0 · Portal production pending
Wallboard grid increases to 60 by 60 cells
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} use Enums 2.0.147's 60 by 60 grid. The preceding local alfa grid was 24 by 24: x/y ranges were 0–23 and w/h ranges 1–24. They are now 0–59 and 1–60. Widgets must still fit without overlap; field names, access checks and revisions are unchanged.
Migration: render and validate the new grid consistently on all clients. Stored coordinates are currently read unchanged and carry no grid-version marker. A width of 12 is one fifth of the new grid rather than one half of the preceding local alfa grid. Review existing layouts before changing their coordinates; use an authorized save and the latest revision for any explicit adjustment, and never repeatedly rescale the same data.
Superseded during alfa; never released to beta or production; see the 60 by 60 change above
Wallboard grid increases to 24 by 24 cells
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} use the 24 by 24 grid from Enums 2.0.146. Widget x/y coordinates now range from 0 to 23 and w/h from 1 to 24, replacing the previous 0–11 and 1–12 bounds. Rectangles must remain within the page without overlap. Field names, zero-based origins, ordered pages/widgets, KIDs, permissions and revision checks are unchanged.
Migration: update renderers, drag/resize calculations, validation and full-page previews to 24 columns and rows before consuming or writing these layouts. Stored coordinates and sizes are retained; reads do not rescale or rewrite existing layouts. A 12-cell width now occupies half the page instead of the full page. To retain the previous relative size and position, explicitly double x/y/w/h for a layout known to use the old grid, using the latest revision in an authorized save. There is no stored grid-version marker: do not infer a migration from coordinates alone or repeatedly rescale layouts. Existing stale-revision and storage-limit errors still apply.
Verified on all five beta apps 2026-10-31 · clients 0.21.0 / Dart 0.11.0 · Portal production pending
Wallboard backgrounds and widget KID styles
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} add per-wallboard ordered numeric c. Previously the compact layout had no background color field. c contains zero to three eColor values: zero selects the default background, one a solid color, two a linear gradient and three a circular gradient. RGB is in the lower 24 bits; the high byte is an ordering value, not opacity. OpenAPI represents eColor as integer/int64 so generated clients retain unsigned 32-bit values above 2147483647. Existing layouts without c remain valid; stored empty arrays are omitted to preserve space, while API responses may include them.
Widget k can now carry canonical Kid.Style values 1 (light) or 2 (dark), including style-only KIDs 1Is and 2Is for widgets without a target. Previously non-empty KIDs were restricted to canonical resource identities for LiveMachines and WashDoc; other widget types required an empty KID. Styled resource KIDs remain subject to the same tenant and resource-grant checks after style is removed. Unknown styles and non-canonical KIDs return 400 invalid-wallboard-widget. A wallboard widget with no style defaults to light.
Migration: allow c in responses and preserve widget k unchanged, including any style. Strict readers may otherwise reject the new field or styled KID. A replacement PUT that omits c preserves existing colors, including for an older client; send "c":[] explicitly to clear them. Retrieve the latest collection and revision before saving, and handle the existing revision and storage-limit errors.
Verified on all five beta apps 2026-10-31 · clients 0.21.0 / Dart 0.11.0 · Portal production pending
Portal assistant requires Agent1 access
AskPortalAssistant — POST /api/v1/assistant/query now requires Agent1 (86) in the current manager's GetCurrentManager.tabs. Previously, the assistant required an active manager session without a dedicated assistant tab. Missing Agent1 now returns HTTP 403 with ProblemDetails code: missing-agent-tab, before question logging, MCP discovery or model use. The request fields question/history and response fields answer/operations/links are unchanged.
Migration: an authorized administrator must grant Agent1 to managers who should use the assistant. Refresh the manager's profile/navigation and handle the new 403 code. Existing Tab/KID/Read permissions still apply separately to every business read; Agent1 grants no additional data access.
Verified on all five beta apps 2026-10-31 · clients 0.21.0 / Dart 0.11.0 · Portal production pending
Wallboard layouts use the Enums 2.0.141 schema
SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards, GetMyManagerWallboards — GET /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} now use layout i/n/p/s instead of id/name/portrait/pages; page n/d/s instead of name/sec/widgets; widget t/k/x/y/w/h instead of type/kid/x/y/w/h. Page and widget id fields are removed; array order defines their position. Orientation p is integer 0 (landscape) or 1 (portrait), replacing the Boolean. Coordinates x/y now range from 0 to 11 instead of 1 to 12. Width and height are unchanged. Display i must be unique across the collection, including orientations; duplicate IDs return 400 invalid-wallboards.
Migration: rename properties, convert orientation to 0/1, subtract one from old coordinates, and omit page/widget IDs. Reread the collection and revision before saving. Both recognized older stored formats remain readable without database writes; names, page/widget order, timing, KIDs and occupied cells are preserved. Previously stored orientation pairs remain readable and visible on approved screens; explicitly move any needed pages and remove the redundant layout before saving the collection. They are never automatically merged or dropped. QR registration appends a new display while preserving existing stored objects. Unknown or ambiguous fields still block replacement. The 4092-character shared budget, authorization, revision checks, scan request displayId and display-route parameters are unchanged.
Verified on all five beta apps 2026-10-31 · clients 0.21.0 / Dart 0.11.0 · Portal production pending
Wallboard layouts use compact property names
SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards requires compact layout properties; GetMyManagerWallboards — GET /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} return them. Layout displayId and isPortrait are now id and portrait; page pageId and displayDurationSeconds are id and sec; widget widgetId, widgetType, column, row, width and height are id, type, x, y, w and h. Names, types, ordering, one-based grid and KID semantics remain. The stored JSON limit decreases from 4096 to 4092 characters; storageLimitCharacters reflects the new limit.
Migration: update clients to read and send the new property names, then retrieve the latest collection and revision before saving. Existing recognized stored layouts are converted in memory when read and written in the compact format on the next successful save; GET never changes stored data. Pages and widgets are retained; malformed or unknown stored fields remain protected from overwrite. Scanning's separate displayId request field and the display route parameter retain their names.
Verified on all five beta apps 2026-10-31 · clients 0.21.0 / Dart 0.11.0 · Portal production pending
Wallboard layouts can contain empty None widgets
SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards, GetMyManagerWallboards — GET /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} now accept or return numeric widgetType: 0 (None), in addition to the previously supported values 1–10. None requires an empty kid; all ID, grid, overlap, revision and authorization checks remain.
Migration: handle type 0 as an empty occupied rectangle. Render no content and make no widget API calls for it. Editors may assign a supported type later. Do not substitute a content widget or reject the entire layout because it contains None.
Verified on all five beta apps 2026-10-31 · clients 0.21.0 / Dart 0.11.0 · Portal production pending
Wallboard layouts use compact property names
GetMyManagerWallboards — GET /api/v1/session/me/wallboards, SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards and GetMyManagerWallboardDisplay — GET /api/v1/session/me/wallboards/display/{displayId} now use the shared Enums model's compact JSON names. Layout displayId/isPortrait become id/portrait; page pageId/displayDurationSeconds become id/sec; widget widgetId/widgetType/column/row/width/height become id/type/x/y/w/h. Values and types retain their meaning, including numeric widget types and one-based grid coordinates. Names, KIDs, pages, widgets and revisions retain their names.
The complete serialized setting's limit changes from 4096 to 4092 characters, including AddMyManagerWallboard — POST /api/v1/session/me/wallboards. Larger writes return 409 wallboards-limit. The Add request still uses {"displayId":"Lobby"}; device-pairing fields and the display route parameter are unchanged.
Migration: update bindings and save payloads to the compact names and reread the collection and revision before editing. API saves reject retired names with 400 invalid-wallboards. Existing stored layouts remain readable without a database rewrite; their next authorized save writes the current format. Mixed legacy/current collections from QR scanning remain supported. Conflicting aliases, unknown fields and malformed stored data block replacement instead of losing data. Permissions, tenant isolation, device approval and optimistic concurrency remain required.
Beta 2026-10-30 · 626ee45e · clients 0.20.0 / .NET and PHP 0.20.1 / Dart 0.10.0 · production pending
Wallboard layout saves require an existing scanned display ID
SaveMyManagerWallboards — PUT /api/v1/session/me/wallboards previously accepted new or renamed wallboards[].displayId values. Each ID must now already exist in the manager's current stored collection, compared case-sensitively under the transaction lock. Otherwise the request returns HTTP 400 wallboard-scan-required. Existing stored displays and the JSON representation remain supported.
Migration: add screens through the QR scanning flow in Wallboard1 first, then reread the collection and revision before editing. Use the existing ID unchanged; change name for the display label. Removed displays require scanning again. Empty collections may still remove layouts without revoking device approval.
Wallboard bearers are restricted to screen session validation
Tokens issued by RedeemWallboardPairing — POST /api/v1/wallboard/pairings/{pairingId}/token and ResumeWallboardSession — POST /api/v1/wallboard/devices/{deviceId}/session no longer permit ordinary business GET/HEAD requests. These now return 403, as writes already did. Only GetCurrentManager — GET /api/v1/session/me is allowed for a screen bearer.
For these screen tokens, GetCurrentManager now returns empty tabs, tabDetails, resourceGrants, operationPermissions and navigationBanks; hasBankAccess is false. Previously these described the approving manager. name, iconKid and organisation are empty; personal preferences use defaults, retentionDays is zero, and databaseAccess/gravatarUrl are null. The manager kid and exact wallboardDisplayId remain available. Field types and normal manager responses are unchanged.
Migration: use an ordinary authorized manager session for Portal business operations. Screen credentials are only for the exact approved display and the signed-device flow. No rescan is required for existing durable device approvals; tenant/environment binding, revocation and automatic proof-based session recovery remain.
GetChecklist moves from GET /api/v1/checklist to GET /api/v1/settlement-checklist. GetChecklistPeriod moves from GET /api/v1/checklist/{periodKid} to GET /api/v1/settlement-checklist/{periodKid}. The former routes are removed without aliases or redirects.
Migration: replace the checklist API path segment with settlement-checklist. Operation IDs, query parameters, canonical period KIDs, response fields, error codes and authorization requirements are unchanged. The HTML example and download move to /examples/settlement-checklist and /examples/settlement-checklist.html. Client packages 0.16.0, PHP 0.16.1 and Dart 0.6.0 include these routes; verified on all five beta apps on 2026-10-28 at commit 28e2e513. Production is pending.
GetOutOfOrderUnits moves from GET /api/v1/units/out-of-order to GET /api/v1/units/out-of-service. RestoreOutOfOrderUnit moves from POST /api/v1/units/{unitKid}/out-of-order/restore to POST /api/v1/units/{unitKid}/out-of-service/restore. The former API routes are removed without aliases or redirects.
Migration: replace the out-of-order path segment with out-of-service in both API URLs. Operation IDs, query parameters, KIDs, expectedRevision, response fields (including outOfOrder), error codes and authorization requirements are unchanged. The browser example calls the new routes. Client packages 0.16.0, PHP 0.16.1 and Dart 0.6.0 include these routes; verified on all five beta apps on 2026-10-28 at commit 28e2e513. Production is pending.
Cycle naming replaces WashDoc routes and document KID fields
GetPublicWashDocWidget — GET /api/v1/public/widgets/washdoc is replaced by GetPublicCycleWidget — GET /api/v1/public/widgets/cycle. Its optional query parameter documentKid becomes cycleKid; JSON fields documentKid and documentKidText become cycleKid and cycleKidText. The canonical KID and display text values and types do not change. Retired or unknown widget query selectors return HTTP 400 invalid-widget-scope instead of selecting the latest running cycle.
For GetUnitDocumentTable, GetUnitDocumentHtml, DownloadUnitDocumentCsv, DownloadUnitDocumentXls, GetUnitDocumentSvg, GetUnitDocumentSvg2, GetUnitDocumentGraph, GetUnitDocumentPng, GetUnitDocumentIcon and GetUnitDocumentNeighbors, the path parameter at GET /api/v1/documents/{cycleKid}/… is renamed from documentKid to cycleKid. Actual URL values and these operation IDs stay the same. The table and graph JSON responses replace documentKid with cycleKid; list item kid fields are unchanged.
The document operations above now return HTTP 400 code invalid-cycle-kid instead of invalid-document-kid for an invalid or cross-tenant document KID. Update code-specific error handling; the HTTP status remains 400.
The alfa preview endpoint GetWashDocChartPresentation — GET /api/v1/public/washdoc-chart/presentation becomes GetCycleChartPresentation — GET /api/v1/public/cycle-chart/presentation. The component moves to /components/cycle/js/cycle-component.mjs with mountCycleChart; the public widget export becomes mountCycleWidget with cycleKid in its options and notification payload. The HTML example is now Cycle viewer, also available as /examples/cycles.html. Old routes and exports are removed.
Migration: update route names, imports, operation names and KID property bindings together; save a fresh cycles.html for local use. Existing KID values, stored data, enum names, manager permissions, tenant isolation and public visibility rules retain their meaning. Portal client packages 0.15.0 and Dart 0.5.0 include this contract; verified on all five beta apps on 2026-10-28 at commit 260959f. Production is pending.
LoginManager — POST /api/v1/session/login and RenewManagerSession — POST /api/v1/session/renew: successful responses now return expiresIn: 864000 (ten days), previously 259200 (three days). The opaque access token expires after the reported interval; its response shape and credential requirements are unchanged. Existing tokens retain their original expiry. Tenant isolation, credential/account revocation and the requirement to renew only after user activity remain in force.
Migration: derive expiry from each response's expiresIn rather than assuming a fixed three-day lifetime. Renew an unexpired session after activity when needed; never keep an unattended session alive. Packaged client documentation is synchronized in clients 0.14.0; deployed to beta 2026-10-27; production is pending.
WashDoc widgets preserve documents without graph measurements
GetPublicWashDocWidget — GET /api/v1/public/widgets/washdoc: an existing public document without drawable numeric measurements previously returned HTTP 422 with no-numeric-graph-data. It now returns HTTP 200 with its normal metadata and graphSvg: null. The string field is now nullable; non-null graph SVGs and all request fields retain their existing meaning. Missing documents, authorization/visibility boundaries, size limits and temporary failures are unchanged.
Migration: check for null before decoding graphSvg. Keep the names, document identity, timestamps and completion marker visible, and show a no-measurements message instead of an error or a fabricated graph. Continue applying refreshAfterSeconds, including zero for completed pinned documents. The official renderer is updated with the API; clients 0.14.0 include this contract; deployed to beta 2026-10-27; production is pending.
GetPublicWashDocWidget — GET /api/v1/public/widgets/washdoc: refreshAfterSeconds previously always returned 60. It now returns 15 while the document is running, 0 when the request pins a completed documentKid, or 60 after completion for unit/latest-following requests that must discover new documents. The field remains an integer; all other request/response fields and public visibility checks are unchanged.
Migration: treat 0 as stop polling, never as an immediate retry. Schedule positive intervals only while visible. A pinned completed document is checked again on a new mount/page load, not continuously. The official renderer is updated with the API; client packages 0.14.0 are synchronized; deployed to beta 2026-10-27; production is pending.
WashDoc widget badge identifies the displayed document
GetPublicWashDocWidget — GET /api/v1/public/widgets/washdoc: the response replaces the display-only string unitKidText with documentKidText. Previously the badge contained the dotted unit identity, for example 999.1383.3.6; it now uses the selected document's Kid.ToDocId representation, for example 999.1383.3.6~1999999198. Canonical documentKid/unitKid, request parameters and public visibility checks are unchanged.
Migration: read documentKidText for the badge and allow the document suffix after ~. Continue using canonical documentKid for requests and navigation. The official widget renderer is updated together with the API; client packages 0.14.0 are synchronized; deployed to beta 2026-10-27; production is pending.
More1 tools move from bank context to the tenant workspace
ConvertToolTime — POST /api/v1/tenant/tools/time and InspectToolKid — POST /api/v1/tenant/tools/kid replace POST /api/v1/banks/{bankKid}/tools/time and POST /api/v1/banks/{bankKid}/tools/kid. The old routes and required bankKid path parameter are removed. JSON request/response fields and operation IDs are unchanged. The trusted site selects the tenant; no tenant or bank selector is required. An active manager, More1 (29), Bank Read and at least one resource grant in the site's tenant remain required. Bank- and location-restricted grants qualify without selecting a context bank. The obsolete 400 invalid-bank error is removed; credential, permission, conversion and availability errors retain their meanings.
Migration: change the request URL to /api/v1/tenant/tools/time or /api/v1/tenant/tools/kid, remove the bank path parameter and reuse the existing manager bearer token and JSON body. Open More1 from the tenant workspace. KID inspection remains a syntax-only operation that grants no access to the inspected identity. Portal clients 0.13.0 and Dart 0.3.0 include the new signatures; rebuild callers without bankKid. Verified on all five beta apps on 2026-10-26 at commit aa51399c. Production is pending.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
Unit document lists use one date and include earlier history
GetUnitDocuments — GET /api/v1/units/{unitKid}/documents: request parameters from/through are replaced by date, a UTC calendar date in yyyy-MM-dd format, defaulting to today. Previously, the default interval covered 24 hours and all searches were limited to 31 days. The list now includes matching document identities from 2000-01-01 through the entire selected day. Response from is the epoch and through is the date at 23:59:59.999Z; their types and the remaining page fields are unchanged. Supplying the removed request parameters returns 400 invalid-document-search. Bank-wide search and full-document measurement limits are unchanged.
Migration: send one UTC date and reset offset when it or sorting changes. Fetch pages lazily, preserving that date. For a total, call GetUnitDocumentsCount — GET /api/v1/units/{unitKid}/documents/count with the same date independently of page loading; it returns {count, from, through}. Both operations retain the same tenant, manager, WashDoc3, Read, scope and retention checks. Verified on beta 2026-10-23 at commit 3c2a88b; clients are synchronized. Production pending.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
WashDoc measurements and signals follow the original unit type
GetUnitDocumentGraph — GET /api/v1/documents/{documentKid}/graph: for Alliance dryers 19/29/30, a historical Level series previously appeared as water level with an unknown unit; it now has group=temperature2, Temperature2 label/localization and °C for bare numeric values. Its stable source name=Level and values are unchanged. LevelTarget/LevelUnfiltered use group=legacyLevel and unknown units. Bare Humidity on those three types uses %. Their signals now accept flags 0–127, interpret heat as bits 32|64, expose nullable airflow from bit 16, and return null inlet/outlet instead of interpreting dryer switches as water valves. Other types retain existing signal semantics. Bare Spin on QW washer types 15/16/17/25/31 no longer claims rpm: series/point units are null and values 0–3 use step=true. Explicit rotation-scale JSON keeps its recorded units.
The added presentation object contains trusted original unitType, kind and preferred groupOrder. Additional actual groups remain present. Migration: use each returned semantic group, label, unit and step flag instead of inferring measurement meaning from its source name. Treat null water signals as inapplicable/unknown, never off, and handle the new airflow signal. Apply preferred ordering only to groups present in the document and retain unlisted groups. PNG, SVG and public widget rendering share these type rules. Stored data, request parameters and authorization are unchanged. Verified on beta 2026-10-23 at commit 3c2a88b; clients are synchronized. Production pending.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
Document tables and downloads omit columns without data
GetUnitDocumentTable — GET /api/v1/documents/{documentKid}/table, DownloadUnitDocumentCsv — GET /api/v1/documents/{documentKid}/table.csv, DownloadUnitDocumentXls — GET /api/v1/documents/{documentKid}/table.xls and GetUnitDocumentHtml — GET /api/v1/documents/{documentKid}/table.html: selected fields previously produced columns even when they contained no values. Now columns omits a field when every cell in the complete authorized document has no numeric value and null, empty or whitespace-only text. Numeric zero, false and nonempty text remain data. The same positions are removed from each rows[].cells array and download headers/cells. Remaining column order, rows, timestamps and values are preserved; no populated field is dropped because its data appears late. A document without populated fields returns empty columns and cell arrays, while downloads retain their timestamp columns.
GetUnitDocumentGraph — GET /api/v1/documents/{documentKid}/graph shares the filtered data: a signal column containing only null/empty values now contributes no signals entries. Absence remains unknown, never false/off. Stored null transitions in a column with actual data are retained.
Migration: construct column mappings from the returned kind/name metadata on every response; do not assume every requested field is present or reuse positional indexes from another document. Treat an omitted field as having no values in this document. Authorization, field-selection limits and storage are unchanged. Verified on beta 2026-10-23 at commit 3c2a88b; clients are synchronized. Production pending.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
Machine types use only the original packed UnitType
GetLocationUnits — GET /api/v1/locations/{locationKid}/units, GetUnitOverview — GET /api/v1/units/{unitKid}, GetUnitGroup — GET /api/v1/units/{unitKid}/groups/{kind}/{group}, GetControllerOverview — GET /api/v1/controllers/{controllerKid}, GetControllerGroup — GET /api/v1/controllers/{controllerKid}/groups/{kind}/{group}, GetUnits — GET /api/v1/units, GetTerminals — GET /api/v1/terminals, GetTenantStatus — GET /api/v1/tenant/status and GetTenantStatusPage — GET /api/v1/tenant/status/page: type interpretation now uses only original eSetting.UnitType, decoded as (value >> 1) & 255. Previously a present direct UnitType2 took precedence. UnitType2 is now ignored and never supplies a fallback. Missing, malformed or out-of-Int64-range UnitType remains unknown; no default type is invented. Stored settings are unchanged.
Affected results include unitType, unitTypeName, unitTypeSource (UnitType when present, null when absent), available setting/state groups, directory type search/filter/sort, SMS exclusion in AutoOutOfOrder, and type-derived progress/widget presentation. Field types and authorization are unchanged, but values and available groups can change. Migration: discard cached type/group metadata, use the returned original type rather than interpreting UnitType2, restart directory cursors and refresh field revisions before editing. Handle unknown types and groups that are no longer available. This supersedes the source-precedence rule recorded in the 2026-10-12 entry. Verified on beta 2026-10-23 at commit 3c2a88b; clients are synchronized. Production pending.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
Unit and terminal cursor options support adaptive page sizes
GetUnits — GET /api/v1/units and GetTerminals — GET /api/v1/terminals: the opaque cursor option binding no longer includes pageSize. Previously, pageSize was fixed by the cursor and limited to 100; it now accepts 1–250 and may change between pages. Cursors issued before this update fail with HTTP 400 invalid-cursor. Migration: discard an old cursor and restart the same filtered query without it. Keep all other query options unchanged, treat cursors as opaque, and continue until nextCursor is null. Tenant, manager, scope, retention and operation checks remain enforced. Other private directory endpoints also accept pageSize 1–250 and permit size changes without changing their filter/scope binding. Response fields and UserBalance are unchanged.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
Reservation cards include resident display details and require User Read
GetLocationReservations — GET /api/v1/locations/{locationKid}/reservations and GetLocationReservationHistory — GET /api/v1/locations/{locationKid}/reservation-history now require User Read alongside Bookings1, Location/Unit Read and existing resource/retention checks. Previously these operations returned occupancy/history without resident metadata or User Read. Authorized items add userNumber and userName strings from the latest resident bank Log7 settings; missing values are empty strings. Items also add nullable canonical userKid, used as the display fallback for a missing number (null when no resident is recorded). Existing time, unit and revision fields are unchanged. Migration: grant User Read to managers who may inspect these details, handle 403 for managers lacking that permission, and render the new strings as plain text. Do not treat failed reads as availability.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
Invalid stored calendars are omitted
GetLocationBookingCalendars — GET /api/v1/locations/{locationKid}/booking-calendars: malformed stored calendars are now omitted from groups, alongside missing calendars. Previously they returned status: Invalid with empty days. Valid calendars on other authorized units remain visible. Migration: treat omitted units as having no valid configured calendar, not unrestricted booking availability; remove expectations of Invalid groups. Storage and authorization failures still return their documented errors.
Beta 2026-10-23 · 3c2a88b · clients synchronized · production pending
Booking calendars return opening-aware dates instead of repeating weeks
GetLocationBookingCalendars — GET /api/v1/locations/{locationKid}/booking-calendars adds optional from (ISO date) and days (1–31, default 14). Invalid date ranges return 400. The response adds timeZone, from, days and per-day date. Previously group days were a seven-day recurring template with potentially negative starts and multi-day durations. They now represent the requested dates with slots clipped to midnight and effective opening hours; type 3 means unknown opening hours. Groups also distinguish different opening schedules.
Migration: render returned dates directly, fetch additional ranges when navigating, remove client-side weekly repetition and opening-hour merging, and display unknown periods as unavailable. This remains configuration rather than booking availability. The current Portal client packages include the dated contract. Verified on all five beta apps on 2026-10-23 at commit 3c2a88b; production pending.
Endpoints:GetCameraCaptures — GET /api/v1/camera and GetCameraCaptureContent — GET /api/v1/camera/{id}/content. New captures return a GUID-based fileName and download filename instead of the original filename stem, FRA/AMS label and capture identity. Related files retain suffixes such as .thumbnail.jpg and .json. Existing stored captures remain readable under their existing names. Original device names and origin regions remain in the metadata JSON.
Migration: treat returned filenames as opaque; do not parse region, device filename or capture identity from them. Continue using API capture identifiers and content links. The filename GUID is not the capture ID. Request fields, response field types and authorization are unchanged. Prepared for beta deployment; production pending.
Negative icon counts display an absolute-value notification badge
Endpoints:GetIconFromSet — GET /api/v1/icon/{iconSet}/{kid}.{format}, GetIconImageFromSet — GET /api/v1/icon/{iconSet}/{kid}/{size}.{format} and GetIconImageWithBackgroundFromSet — GET /api/v1/icon/{iconSet}/{kid}/{backColor}/{size}.{format}. Affected: rendered notification badge for the signed count encoded in the icon KID.
Previously, zero and negative counts hid the badge, and positive counts used a red background with white digits. Zero still hides it; negative counts now show the full absolute value with a red background and white digits. Positive counts now use a white background and black digits. All signed Int64 values, including Int64.MinValue, remain accepted. KID encoding, response media types and operation IDs are unchanged.
Customer action
If negative counts previously suppressed a badge in your integration, encode count zero instead. To retain the former red badge for a positive count, encode its negative value; otherwise retain the positive count for the white badge. Do not compute the absolute value using signed Int64 arithmetic for its minimum value. Portal clients 0.7.2 include the current contract documentation. Verified on beta on 2026-10-14 at commit 747c9e9; production pending.
Beta 2026-10-13 · 353b2ae · clients 0.7.1 · production pending
Packed unit types retain all eight type bits
GetLocationUnits — GET /api/v1/locations/{locationKid}/units, GetUnitOverview — GET /api/v1/units/{unitKid}, GetUnitGroup — GET /api/v1/units/{unitKid}/groups/{kind}/{group}, GetUnits — GET /api/v1/units, GetTerminals — GET /api/v1/terminals and controller overview/group equivalents now decode legacy UnitType as (value >> 1) & 255, previously & 63. For example, raw 132 now identifies type 66 instead of type 2. Response field types are unchanged, but unitType, unitTypeName, available setting/state groups and directory type filtering/sorting can change. A present direct UnitType2 still takes precedence, including malformed values returning null without fallback.
Migration: use the returned type and group lists, discard cached type metadata and restart directory pagination. Refresh setting revisions before writing: edits and history are governed by the corrected type, and previously accessible groups may return 404. Verified on all five beta apps on 2026-10-13 at commit 353b2ae; packaged Portal clients 0.7.1 are synchronized. Production pending.
Beta 2026-10-13 · 353b2ae · clients 0.7.1 · production pending
Unit progress uses only elapsed expected time, clamped to 0–100%
GetLocationUnits — GET /api/v1/locations/{locationKid}/units, GetUnitOverview — GET /api/v1/units/{unitKid}, GetUnitGroup — GET /api/v1/units/{unitKid}/groups/{kind}/{group}: progress.percent now uses floor(clamp((now − Started)/(Done − Started) × 100, 0, 100)). Previously lifecycle, connection and sequence state could suppress the percentage, estimated progress stopped at 99, and 100 required DONE. Valid timing now returns status Estimated and 0–100 regardless of those states; at/after the expected end percent is 100 and remainingSeconds is 0. Before start, percent is 0. Missing/invalid times return UnknownEndTime and null percent/remainingSeconds. Field types are unchanged. The same calculation is available through the new optional fields=progress on GetUnits — GET /api/v1/units.
Migration: accept Estimated with 100 percent; do not infer physical completion from progress status or percent. Use cycle for device state. Remove assumptions that elapsed estimates return EstimateExpired or that disabled/disconnected units always have null percentages. Verified on all five beta apps on 2026-10-13 at commit 353b2ae; packaged Portal clients 0.7.1 are synchronized. Production pending.
Beta 2026-10-13 · 353b2ae · clients 0.7.1 · production pending
Controller identities use MainId and retain the first unit as a child
GetLocationUnits — GET /api/v1/locations/{locationKid}/units, GetUnitOverview — GET /api/v1/units/{unitKid}, GetUnitGroup — GET /api/v1/units/{unitKid}/groups/{kind}/{group}, GetUnits — GET /api/v1/units and GetTerminals — GET /api/v1/terminals: optional terminal.kid previously identified the main Unit (UnitId). It now identifies a Controller (MainId, UnitId=0). The terminal.name field now uses the main unit’s eState.ComputerName, matching GetTerminals, instead of eSetting.Name; absent ComputerName returns an empty string. Nullability and icon fields are unchanged; each row's own unit KID is unchanged. GetUnits query terminalKid now requires this Controller KID instead of a Unit KID, and includes the first unit as well as mapped children instead of excluding it. Old Unit KIDs return 400 invalid-terminal.
Migration: refresh cached names and hierarchy metadata, display terminal.name as reported computer text (handle empty names), group by the returned terminal.kid, and pass it unchanged as terminalKid. Keep the first unit as its own child; do not compare its KID to the controller KID. Restart directory cursors and discard stale cached parent identities. Controller overview/group routes use the Controller KID; their unit.kid remains the underlying storage unit. Verified on all five beta apps on 2026-10-13 at commit 353b2ae; packaged Portal clients 0.7.1 are synchronized. Production pending.
Beta 2026-10-13 · 353b2ae · clients 0.7.1 · production pending
Self-registration rejects unsupported email languages
RequestManagerSignUp — POST /api/v1/session/signup: optional nullable language now accepts only the exact lowercase strings en, da and es when a non-null value is supplied. Previously any string was accepted, with values other than exact da/es silently using English. Empty strings, whitespace, regional tags, uppercase and unknown values now return HTTP 400 ValidationProblemDetails with errors.Language before account creation or mail queueing. Omitting the field or sending null still uses English; valid requests retain the existing response contract.
Migration: map browser or application language preferences to one of the three supported lowercase codes. For English, send en, omit the field or send null; do not send an empty string or an unprocessed regional language code. Handle language validation errors before resubmitting. Verified on all five beta apps on 2026-10-13 at commit 353b2ae; packaged Portal clients 0.7.1 are synchronized. Production pending.
Beta 2026-10-13 · 353b2ae · clients 0.7.1 · production pending
Public purchase amounts are grouped by currency
GetPublicPurchases — GET /api/v1/public/statistics/purchases: the top-level decimal amount and nullable string currency are removed. Previously all qualifying purchase amounts were combined and labelled with MAX(Currency). The response now contains a non-null currencies array of {currency, count, amount} objects: one group per currency, with a nullable string currency, integer purchase count and decimal amount in major currency units, calculated as -SUM(Amount)/100 within that group. Missing currency remains null in its own group. No combined monetary total or conversion is returned.
The top-level count remains the total number of purchases and equals the sum of group counts. With no purchases, the former amount: 0, currency: null are replaced by currencies: []; count remains zero. tenantKid, lookbackHours, sinceUtc, measuredAtUtc, the request, filters and access rules are unchanged.
Migration: iterate over currencies and display each group's amount with its own currency; use the top-level count for the overall purchase count. Handle an empty array and a null currency without assuming a known currency. Stop reading the removed top-level fields and do not sum amounts across currencies. Verified on all five beta apps on 2026-10-13 at commit 353b2ae; packaged Portal clients 0.7.1 are synchronized. Production pending.
Beta 2026-10-13 · 353b2ae · clients 0.7.1 · production pending
Self-registration creates a pending manager before email delivery
RequestManagerSignUp — POST /api/v1/session/signup: required request fields password and confirmPassword added. Previously email/name/organisation queued proof without creating an account; now the password is chosen immediately and a disabled manager plus manager-bound verification mail are committed atomically. Existing-address processing remains non-disclosing 202 accepted.
ConfirmManagerSignUp — POST /api/v1/session/signup-confirmation: password and confirmPassword removed; request contains only token. Previously confirmation created a manager and returned 201 manager-created; now it activates the existing pending manager and returns 200 email-verified. No business access is granted.
Migration: collect matching 12–128 printable ASCII passwords on the initial form, send them with signup, send only the verification token on confirmation, and expect 200/email-verified. Tokens from the previous local flow are invalid; request a new link. Verified on all five beta apps on 2026-10-13 at commit 353b2ae; packaged Portal clients 0.7.1 are synchronized. Production pending.
Release 2026-10-10 · available on this host · clients 0.6.1
Terminal directory names use the reported computer name
GetTerminals — GET /api/v1/terminals: items[].name now reads eState.ComputerName from tenant-bound Log24 instead of eSetting.Name. Missing computer names return an empty string; there is no settings-name fallback. Name filtering and sorting use the new source. Optional string fields/sorts added: versionMinor, bootReason, booted, firmware, storageCardSerialNumber, page, backLight. They are null unless requested through fields; selected missing values are empty strings. Booted uses eSetting.Booted, the other added values use eState.
Migration: treat name as the reported computer name, handle empty names, and restart pagination after release. Existing stored names are preserved. GetUnits and UserBalance name behavior is unchanged.
Release 2026-10-10 · available on this host · clients 0.6.1
Bank and location directory tab assignments corrected
GetLocations — GET /api/v1/locations and GetActiveLocationCount — GET /api/v1/locations/active-count now require Locations1 (65), previously Banks2 (5). Without tab 65 these operations return 403. The new unreleased GetBanks — GET /api/v1/banks and GetActiveBankCount — GET /api/v1/banks/active-count require Banks2 (5), previously Locations1 (65).
Migration: review and explicitly assign tab 65 for location directory access and tab 5 for bank directory access. Stored assignments and numeric enum IDs are not rewritten. Resource scopes and operation permissions still apply. Request and response fields are unchanged; active-count iconKid values use the corresponding tab metadata. UserBalance is unchanged.
Release 2026-10-10 · available on this host · clients 0.6.1
Tab 66 is named Terminals1
GetCurrentManager — GET /api/v1/session/me, GetManager — GET /api/v1/managers/{managerKid}, SetManagerTab — POST /api/v1/managers/{managerKid}/tabs/{tabId} and SetManagerPermissionRole — POST /api/v1/managers/{managerKid}/permission-role: tab objects with id:66 now use name:"Terminals1" instead of name:"Disp66", including the available-tab catalog. The numeric identity and stored tab assignments remain unchanged.
Migration: identify tabs by their stable numeric ID, update any name comparisons for tab 66, and treat its terminal-directory access as tenant-bound. This does not automatically assign tab 66 or grant resource/operation permissions. Clients 0.6.1 include this contract. UserBalance is unchanged.
Release 2026-10-10 · available on this host · clients 0.6.1
Role replacement requires Tabs and Kids permissions
SetManagerPermissionRole — POST /api/v1/managers/{managerKid}/permission-role: every role now requires the caller's Read and Write permissions on both Tabs and Kids, checked from the fresh authorization snapshot inside the transaction before any write. Previously only accounting checked Tabs and no role checked Kids, although all roles replaced both permission masks. Newly rejected requests return 403 with missing-tabs-read, missing-tabs-write, missing-kids-read or missing-kids-write. Request and success-response fields are unchanged.
Migration: require both categories' Read/Write permissions before offering role replacement, handle these 403 codes and obtain the missing permissions through an authorized administrator. Existing manager, tenant and own-edit checks remain. UserBalance is unchanged.
Release 2026-10-07 · available on this host · clients 0.5.2
Default manager retention is 10 days
GetCurrentManager — GET /api/v1/session/me, GetMyManagerProfile — GET /api/v1/session/me/profile, GetManagers — GET /api/v1/managers and GetManager — GET /api/v1/managers/{managerKid}: retentionDays now defaults to 10 when the stored setting is absent or SQL NULL, previously 0. Explicit values, including 0, are preserved; malformed or negative values still resolve to 0. This also changes the default visibility window for otherwise authorized deleted records; no records are physically deleted or migrated. Integrations should use the returned value; save an explicit 0 if deleted records must stay hidden.
Release 2026-10-07 · available on this host · clients 0.5.2
Remove service permission, KID and tab assignments
GetService — GET /api/v1/services/{serviceKid}, SetServiceProfileField — POST /api/v1/services/{serviceKid}/profile/{field} and GenerateServiceApiKey — POST /api/v1/services/{serviceKid}/api-key: remove the previously unreleased access object (nested under details for key generation), including resourceGrants, tabs, availableTabs, operationPermissions, kidsRevision, tabsRevision, canEdit, canEditTabs and canEditKids.
Removed operations: SetServicePermission — POST /api/v1/services/{serviceKid}/permissions/{resource}, SetServicePermissionRole — POST /api/v1/services/{serviceKid}/permission-role, SetServiceTab — POST /api/v1/services/{serviceKid}/tabs/{tabId} and SetServiceKid — POST /api/v1/services/{serviceKid}/kids. Their request bodies and response contracts are no longer supported.
Migration: remove service access editors and stop sending assignment requests or reading access fields. Each business endpoint explicitly authorizes the authenticated eUserId; synchronization requires ServiceSync. Service authentication, account state, key revocation, tenant isolation and manager authorization for service administration remain enforced. Existing stored access settings are preserved but ignored for service authorization. The Tabs/Kids entry below describes the final manager-only contract. UserBalance is unchanged. Clients 0.5.2 include this contract.
Release 2026-10-07 · available on this host · clients 0.5.2
Logo parts use URL path segments
GetKombineLogo, GetKombineLogoSized and GetKombineLogoWithBackground — GET /api/v1/logos/kombine/{color}.svg, /{color}/{width}.svg and /{color}/{background}/{width}.svg: the earlier local, unreleased optional parts query parameter has been removed. These routes return the complete symbol.
Migration: replace /api/v1/logos/kombine/black.svg?parts=W with /api/v1/logos/kombine/W/black.svg (GetKombineLogoParts). The intermediate unreleased /kombine/parts/{parts}/... routes have also been replaced by /kombine/{parts}/...; remove the literal parts/ segment. Combinations use the same segment, for example /api/v1/logos/kombine/NS/black.svg. Width and background/width variants use GetKombineLogoPartsSized and GetKombineLogoPartsWithBackground. All parameters precede the final .svg. Parts accepts 1–4 letters N/E/S/W, case-insensitively; invalid selections return 400 with invalid-logo-parameters. SVG geometry and existing full-symbol contracts are unchanged. Clients 0.5.2 include this contract.
Release 2026-10-07 · available on this host · clients 0.5.2
Independent Tabs and Kids permissions; nine-category role requests
SetManagerPermissionRole — POST /api/v1/managers/{managerKid}/permission-role: expectedFlags previously required seven categories; now exactly nine are required, adding Tabs and Kids. Incomplete requests return 400 invalid-permission-role. Role responses and operationPermissions projections add these two resources; match by name rather than position. Full support presets set both to 63; accounting/caretaker set both to Read (1). Existing stored values are preserved; absent values default to Read, malformed values grant nothing.
SetManagerTab — POST /api/v1/managers/{managerKid}/tabs/{tabId} and SetManagerKid — POST /api/v1/managers/{managerKid}/kids now additionally require the caller's respective Tabs/Kids Read and Write. Applying accounting also requires Tabs Read/Write. Previously these operations relied on the parent Managers edit permission and existing scope checks. New 403 codes: missing-tabs-read, missing-tabs-write, missing-kids-read, missing-kids-write. Existing parent, tenant and own-edit checks remain.
Migration: reread the object and send all nine expectedFlags, with explicit null for invalid masks. Handle independent manager canEditTabs/canEditKids hints. Role canEditTabs may differ from canEditPermissions. Grant the new write flags explicitly through an authorized permission editor before changing assignments; there is no automatic data migration. UserBalance is unchanged. Clients 0.5.2 include this manager contract.
Release 2026-10-05 · available on this host · clients 0.4.1, PHP 0.4.2
Location directory optional fields must be requested
GetLocations — GET /api/v1/locations: previously vismaCustNo was always a string and both activation-code fields were populated whenever authorized. They now default to null unless explicitly selected with the new comma-separated fields query parameter. Select vismaCustNo,bankActivationCode,locationActivationCode to retain the previous values (code permissions still apply). New optional fields are address, zip, longitude and latitude. Status, canonical KIDs, names and icons remain present. The page adds a normalized fields array.
Migration: request every optional field your client consumes and accept null for unselected values. Send the same selection on every page; restart without the old cursor after changing it. Unknown fields return 400 invalid-fields, and changing a cursor's selection returns 400 invalid-cursor. Packaged clients 0.4.1 include this contract.
Release 2026-10-05 · available on this host · clients 0.4.1, PHP 0.4.2
Version 2 QR noise and checksum expanded to 30 bits
GetBankUserActivation — GET /api/v1/banks/{bankKid}/users/{userKid}/activation: in qrCodeDataV2, noise and checksum (the fourth and fifth decoded values) change from unsigned 24-bit values (0–16777215) to unsigned 30-bit values (0–1073741823). The checksum modulus changes from 16777216 to 1073741824: (((bankCode * 31 + userCode) * 31 + seconds) * 31 + noise) % 1073741824. Noise is freshly generated with a cryptographic random generator. The five-value order and JSON string representation are unchanged; version 1 is unchanged.
Migration: continue decoding five values, expand range validation for both noise and checksum to 30 bits, and use the new modulus at each checksum step with UInt64 intermediates. Regenerate QR codes from the earlier unreleased version 2 format; no old-modulus fallback. Packaged clients 0.4.1 and PHP 0.4.2 include this contract.
Development revision · superseded before beta release
Version 2 QR payload adds random noise before the checksum
GetBankUserActivation — GET /api/v1/banks/{bankKid}/users/{userKid}/activation: qrCodeDataV2 changes from four encoded numbers (bankCode, userCode, seconds, checksum) to five (bankCode, userCode, seconds, noise, checksum). Noise is a fresh cryptographically generated unsigned 24-bit value, 0–16777215. The checksum remains 24-bit but now includes noise: (((bankCode * 31 + userCode) * 31 + seconds) * 31 + noise) % 16777216. The JSON field remains a non-null string; version 1 is unchanged.
Migration: decode five values with FlexCipherLongs.Parse(5, fragment), validate the fourth and fifth values as 24-bit, and include noise when verifying the fifth value. Reduce after each arithmetic step using UInt64 intermediates. Regenerate earlier unreleased version 2 QR codes; no compatibility fallback. Noise may repeat and is not authentication or replay protection. Packaged clients will be synchronized at beta preparation.
Development revision · superseded before beta release
Version 2 QR checksum changed to weighted 24-bit arithmetic
GetBankUserActivation — GET /api/v1/banks/{bankKid}/users/{userKid}/activation: the fourth decoded value in qrCodeDataV2 previously used the unsigned 16-bit sum (bankCode + userCode + seconds) % 65536. It now uses the unsigned 24-bit value ((bankCode * 31 + userCode) * 31 + seconds) % 16777216, in the range 0–16777215. The JSON field remains a non-null string, and FlexCipherLongs still encodes four numeric values. This is a logical three-byte checksum, not a separate fixed-width byte field. Version 1 and permission requirements are unchanged.
Migration: update version 2 readers to validate the new range and formula. Reduce each input modulo 16777216 before multiplication/addition and use wide intermediate integers to avoid overflow. Regenerate QR codes from the earlier unreleased version 2 format; the old checksum is not accepted as a fallback. This checksum is error detection, not authentication. Packaged clients will be synchronized during beta release preparation.
Release 2026-10-05 · available on this host · clients 0.4.1, PHP 0.4.2
Explicit version 1 name for resident QR data
GetBankUserActivation — GET /api/v1/banks/{bankKid}/users/{userKid}/activation: the response field qrCodeData is renamed to qrCodeDataV1. The old field is removed without an alias. The value remains a non-null JSON string with the unchanged version 1 FlexCipherLongs payload, or an empty string when no tenant activation URL exists. qrCodeDataV2 and authorization requirements are unchanged.
Migration: rename the response property in your model and read qrCodeDataV1 when rendering version 1. No QR payload or decoding changes are needed. Packaged clients will be synchronized during beta release preparation.
Release 2026-10-02 · available on this host · clients 0.3.1
Compact reservation rules, complete role requests and canonical map route
GetLocationBookingRules — GET /api/v1/locations/{locationKid}/booking-rules: previously each groups entry contained a complete policy for units sharing calendar/settings. Now groups contain the compact presentation: identical rules are combined; shared rules appear once in a section with common:true, localized name and optional help, followed by differences. Each section identifies its applicable units. Render groups in order and combine applicable common and specific rules when evaluating the displayed policy for a unit. Do not treat a differences section as a complete policy or combine reservation quotas. The development-only displayGroups field is removed; use groups.
SetManagerPermissionRole — POST /api/v1/managers/{managerKid}/permission-role: expectedFlags must include all seven categories. Previously omitting only Service preserved its stored value; now incomplete requests return 400 invalid-permission-role without writes. Read the current matrix and send Managers, Installer, Service, Bank, Location, Unit and User.
GetPublicDisp73 — GET /api/v1/public/displays/Map1: the old /api/v1/public/displays/disp73 alias is removed and returns 404. Update stored URLs to Map1. The operation ID and canonical route response are unchanged. UserBalance contracts are unchanged.
Release 2026-10-01 · available on this host
Presentation response fields renamed to IconKid
Breaking response change:icon, bankIcon and unitIcon become iconKid, bankIconKid and unitIconKid, including nested objects, navigation, tabs, audit editors and document columns. They remain JSON strings. Previously an enum name; now an API-computed icon identity. Only Kid.Icon returns eIcon.ToString(); extra text/count/colour/icons return canonical Kid.ToString(). Empty/unavailable metadata remains an empty string. Object numbers are embedded in Text; calendar Text is the current day of month in Europe/Copenhagen. Rendering an existing filename does not consult the clock.
Stable operation ID
Unchanged method/path
GetCurrentManager
GET /api/v1/session/me
GetMyManagerProfile
GET /api/v1/session/me/profile
SetMyManagerProfileField
POST /api/v1/session/me/profile/{field}
GetManagers
GET /api/v1/managers
GetManager
GET /api/v1/managers/{managerKid}
SetManagerProfileField
POST /api/v1/managers/{managerKid}/profile/{field}
SetManagerTab
POST /api/v1/managers/{managerKid}/tabs/{tabId}
SetManagerPermissionRole
POST /api/v1/managers/{managerKid}/permission-role
GetInstallers
GET /api/v1/installers
GetInstaller
GET /api/v1/installers/{installerKid}
SetInstallerIcon
POST /api/v1/installers/{installerKid}/icon
GetServices
GET /api/v1/services
GetService
GET /api/v1/services/{serviceKid}
SetServiceProfileField
POST /api/v1/services/{serviceKid}/profile/{field}
GenerateServiceApiKey
POST /api/v1/services/{serviceKid}/api-key
GetLocations
GET /api/v1/locations
GetBankLocations
GET /api/v1/banks/{bankKid}/locations
GetLocationUnits
GET /api/v1/locations/{locationKid}/units
GetUnitOverview
GET /api/v1/units/{unitKid}
GetUnitGroup
GET /api/v1/units/{unitKid}/groups/{kind}/{group}
SetUnitSetting
POST /api/v1/units/{unitKid}/groups/settings/{group}/{setting}
GetUnitSettingHistory
GET /api/v1/units/{unitKid}/groups/settings/{group}/{setting}/history
GetBankUsers
GET /api/v1/banks/{bankKid}/users
GetBankUserWorkspace
GET /api/v1/banks/{bankKid}/users/{userKid}/workspace
CreateBankUser
POST /api/v1/banks/{bankKid}/users
ExecuteBankUserCommand
POST /api/v1/banks/{bankKid}/users/{userKid}/commands
GetBankBookings
GET /api/v1/banks/{bankKid}/bookings
ExecuteBankBookingCommand
POST /api/v1/banks/{bankKid}/bookings/{bookingKid}/commands
GetBankAccount
GET /api/v1/banks/{bankKid}/account
GetBankDocuments
GET /api/v1/banks/{bankKid}/documents
GetUnitDocumentTable
GET /api/v1/documents/{documentKid}/table
GetTenantStatus
GET /api/v1/tenant/status
SearchBanks
GET /api/v1/search/banks
SearchBankActivation
GET /api/v1/search/bank-activation
GetSearchBank
GET /api/v1/search/banks/{bankKid}
SearchLocations
GET /api/v1/search/locations
SearchLocationActivation
GET /api/v1/search/location-activation
SearchUsers
GET /api/v1/search/users
SearchUserSms
GET /api/v1/search/user-sms
SearchUserActivation
GET /api/v1/search/user-activation
Migration: rename response model properties and pass the supplied string unchanged, URL-encoded, to /api/v1/icon/{iconSet}/{kid}.svg. Stop interpreting every value as an enum name or composing KIDs in the portal. Use public GetIconPresentation — GET /api/v1/icon/presentation for presentation options and a fresh calendar identity. Icon setting writes and availableIcons still use enum names; service objects also expose iconName for selection. GetActiveLocationCount (GET /api/v1/locations/active-count) additionally returns a ready-to-render iconKid with its badge. Permissions and tenant binding are unchanged; these values grant no access.
Release: 2026-10-01, client version 0.2.1. Generated clients, OpenAPI snapshots and downloadable packages are synchronized with this contract. This release label applies to the version served by this host; beta and production are promoted independently. Existing image paths and image caching are unchanged.
Release 2026-10-01 · available on this host
Icon images · Canonical KID with icons, count, color and text; required asset set
Affected requests:kid previously accepted an eIcon name, numeric value/index or substring. It now first parses a canonical Kombine.Flex.Kid.ToString() and reads Kid.Icons, Kid.Count (Int64), Kid.Color and Kid.Text. Separate count/color/text/sub path fields are removed. Color uses the low 24 bits as opaque RGB (0 = black; the high byte is ignored, as for Flex eColor). Text is UTF-8, case-sensitive and limited to 128 characters without controls. Encoded canonical KIDs are limited to 2048 characters. If that fails, an exact case-insensitive eIcon name is accepted with count zero, black and empty text. Numeric/index/substring enum lookup is no longer a fallback; invalid input returns 400. The first list entry is the main icon and the second is the under-icon. A missing/none second entry means no under-icon; later entries do not affect rendering. Every list entry must be a defined eIcon value. An empty list uses eIcon.none. Other KID fields cause no business lookup or permission change. Count ≤ 0 hides the badge. Positive counts display in full in a red capsule whose straight middle widens between circular ends. Very long labels widen the SVG canvas; no count is abbreviated.
Operation ID
Previous method/path
New method/path
GetIconFromSet
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}.{format}
GET /api/v1/icon/{iconSet}/{kid}.{format}
GetIconImageFromSet
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{size}.{format}
GET /api/v1/icon/{iconSet}/{kid}/{size}.{format}
GetIconImageWithBackgroundFromSet
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{format}
GET /api/v1/icon/{iconSet}/{kid}/{backColor}/{size}.{format}
GetIcon2Svg (removed)
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}.{format}
Use GetIconFromSet with explicit line or g.
GetIcon2Image (removed)
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}/{size}.{format}
Use GetIconImageFromSet with explicit line or g.
GetIcon2ImageWithBackground (removed)
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{format}
Use GetIconImageWithBackgroundFromSet with explicit line or g.
Customer action
The interim local route /api/v1/icon/{iconSet}/{kid}/{sub}.{format} is also replaced by /api/v1/icon/{iconSet}/{kid}.{format}. Append the former sub value as the second entry of Kid.Icons and remove its path segment; the size/background forms remove that segment in the same way.
Add the main icon and optional under-icon to Kid.Icons in that order, set Count, Color and Text on a Kid, URL-encode ToString(), remove the count/color/text/sub segments and select the set explicitly (line preserves the former default). For example, Kid.Icons = [house, check], Count = 7, Color = 0x336699, Text = "A12" produces 413132x7qE20i11Bi336699Ic: use /api/v1/icon/line/413132x7qE20i11Bi336699Ic.svg. For count zero, black and empty text, /api/v1/icon/line/house.svg also works. Update stored links/builders; old shapes are not aliases and overlapping paths can be interpreted as different requests. Rendering formats, set fallback, cache/304 behavior and the public asset catalog remain unchanged. Unknown sets/missing assets return 404; invalid parameters return 400.
Release: 2026-10-01, client version 0.2.1. Generated clients, OpenAPI snapshots and downloadable packages are synchronized with this contract. Upgrade the client and migrate the removed routes as described above. This release label applies to the version served by this host; beta and production are promoted independently.
Release 2026-09-28 · available on this host
Account2 · Retention-aware identities, decoded descriptions and reversal eligibility
Operation ID
Method/path
GetBankAccount
GET /api/v1/banks/{bankKid}/account
ExportBankAccount
GET /api/v1/banks/{bankKid}/account/export
GetBankAccountRevision
GET /api/v1/banks/{bankKid}/account/revision
ReverseBankAccountEntry
POST /api/v1/banks/{bankKid}/account/{transactionKid}/reversal
Previous: listing/export did not apply tenant/manager retention settings. userKid, userName and userNumber could identify expired entries; descriptions could contain partial legacy text or internal payment markers. Ordinary reversal eligibility did not explicitly reject expired or payment-managed consumption.
New: tenant LawAccountingYears and LawSurveillanceDays, with positive manager overrides, mask expired identities in general views: userKid becomes the bank's GDPR user KID (UserId 1000), userName/userNumber become empty strings, description contains only the transaction type, isAnonymized is true and canReverse is false. Zero/missing/invalid retention values retain no identity. With an explicit userKid, expired entries are excluded from rows and totals. CSV/XLSX applies the same rules with unchanged columns. Descriptions use the full shared decoder; internal payment IDs are removed. Payment-managed and expired entries return 422 reversal-unavailable on ordinary reversal. Revision values now include retention visibility and caches are separated by manager. Amount representation and request fields remain unchanged.
Migration: display an anonymous label when isAnonymized is true and never link it to a resident profile. Do not interpret description text as a payment identifier; use the additive paymentKind field (Credit, ReserveRefund, Managed or empty). Honor canReverse and handle 422 without retrying. Do not merge pages with different revisions. The additive documentKey/documentId and documents fields group only filtered lines on each page; merge groups by key across pages, not DocId alone. Existing flat items and row pagination remain supported.
Release: 2026-09-28. The clients and downloadable packages have been synchronized with this contract; package version 0.1.0 is retained and no external registry publication is claimed.
Release 2026-09-28 · available on this host
Icon images · Missing assets are searched in other local sets
Affected responses: an icon missing from the selected set previously returned HTTP 404 even when another local set contained it. Rendering now searches for the same eIcon identity in the selected set first, then other packaged sets in ordinal alphabetical order. Each main/under-icon resolves independently. A matching asset returns HTTP 200 in the requested format, or 304 for a matching conditional request. Unknown sets and icons absent from every local set still return 404. Request fields, format encodings and existing images in the selected set are unchanged. There is no external-server or database fallback. Included in release 2026-09-28.
Operation ID
Method/path
GetIcon2Svg
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}.{format}
GetIcon2Image
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}/{size}.{format}
GetIcon2ImageWithBackground
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{format}
GetIconFromSet
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}.{format}
GetIconImageFromSet
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{size}.{format}
GetIconImageWithBackgroundFromSet
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{format}
Customer action
Do not interpret a successful render as proof that the asset belongs to the requested set. Use the documentation set catalogs to inspect actual membership. For example, /api/v1/icon/g/house/black/0/0/none.svg now renders the house asset from line. Paths without a set still prefer line. Clients that implement their own 404-based set search can rely on server-side lookup instead. Refresh rendered images or allow the existing ten-minute browser cache to expire; renderer build changes invalidate disk-cache entries.
Endpoints:GET /api/v1/logos/kombine/{color}.svg, GET /api/v1/logos/kombine-text/{color}.svg and GET /api/v1/logos/kombine-logo-text/{color}.svg. The SVG response root previously had width="256" and a proportional numeric height (256, 48.162712 or 51.2). These attributes are now omitted. The unchanged viewBox and preserveAspectRatio="xMidYMid meet" let the complete artwork fit and center in its viewport without cropping or stretching. Routes with an explicit width retain their pixel dimensions. Colors, geometry, content type, operation IDs and status codes are unchanged. Included in release 2026-09-28.
Customer action
If your layout or SVG parser requires fixed dimensions, use the corresponding /{color}/256.svg route, or specify dimensions on the embedding element. Do not assume the unsized response contains numeric width/height attributes. Renderer cache keys have changed; clients can refresh or wait for the existing 600-second browser cache to expire.
Release 2026-09-28 · available on this host
LoginManager · Duplicate credentials now select one active manager
Endpoint:POST /api/v1/session/login. Affected: the status and account selection when multiple managers match both email and password. Previously this case returned HTTP 401. It now returns HTTP 200 for the active, non-deleted manager with the newest eSetting.Alive krumb MS2000, after atomically clearing Password on the other matching managers. Activity uses the krumb timestamp, not Text; missing or invalid timestamps rank last. Equal timestamps, including all unknown, are resolved by the lowest UserId. The selection uses a fresh locked read in the cleanup transaction. Different passwords sharing an email are unchanged. No active match means no cleanup and the lowest matching account determines the existing HTTP 403 account-state error. Cleanup/storage failures or more than 100 matching rows return HTTP 503. Request fields and the token response representation are unchanged. Included in release 2026-09-28.
Customer action
Do not rely on duplicate credentials returning 401. Call GetCurrentManager after login and use its identity and permissions; grants from duplicate accounts are not combined. Sessions of accounts whose passwords are cleared become invalid, subject to the existing maximum 60-second cache on other API instances. To keep distinct accounts usable, give them distinct credentials before this change is released. Do not automatically retry an uncertain login/cleanup response.
Affected requests: remove the literal sets segment after /api/v1/icon/. The previous set-specific paths are removed. The operation IDs, parameter names, rendering, response formats and cache behavior are unchanged. Included in release 2026-09-28.
Operation ID
Previous method/path
New method/path
GetIconFromSet
GET /api/v1/icon/sets/{iconSet}/{kid}/{color}/{count}/{text}/{sub}.{format}
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}.{format}
GetIconImageFromSet
GET /api/v1/icon/sets/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{size}.{format}
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{size}.{format}
GetIconImageWithBackgroundFromSet
GET /api/v1/icon/sets/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{format}
GET /api/v1/icon/{iconSet}/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{format}
Customer action
Remove sets/ from set-specific image URL builders and stored links. For example, use /api/v1/icon/line/house/000000/7/A12/none/128.svg. Keep the set name and all other path values. Existing icon-first routes without a set name still use line; known set names take precedence where route shapes overlap. The rebuilt clients in release 2026-09-28 use these paths.
Release 2026-09-28 · available on this host
GetIcon2Svg / GetIcon2Image / GetIcon2ImageWithBackground · Icon paths and format parameter
Affected requests: the URL prefix for all three GET image operations changes from /Icon2 to /api/v1/icon. The former routes are removed. Operation IDs are retained. The extension parameter is now named format instead of fileType on the sized routes; it is a required path parameter. The short route replaces its fixed .svg suffix with required .{format} and also accepts raster formats, using 128 × 128 pixels when no size is supplied. Existing SVG and sized-image rendering semantics, content types and conditional caching are unchanged. Included in release 2026-09-28.
Operation ID
Previous method/path
New method/path
GetIcon2Svg
GET /Icon2/{kid}/{color}/{count}/{text}/{sub}.svg
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}.{format}
GetIcon2Image
GET /Icon2/{kid}/{color}/{count}/{text}/{sub}/{size}.{fileType}
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}/{size}.{format}
GetIcon2ImageWithBackground
GET /Icon2/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{fileType}
GET /api/v1/icon/{kid}/{color}/{count}/{text}/{sub}/{backColor}/{size}.{format}
Customer action
Update image URL builders and stored links to use /api/v1/icon/. Use format when binding parameters by their OpenAPI names, and pass svg explicitly for the former SVG-only operation. Keep presentation values in their existing path segments; no query parameters are required. For example, use /api/v1/icon/house/000000/7/A12/none.svg or /api/v1/icon/house/000000/7/A12/none/128.png. Continue URL-encoding individual path values. The rebuilt clients in release 2026-09-28 use these paths.
Release 2026-09-28 · available on this host
GenerateServiceApiKey · Generated keys now start with kt_
Affected: the response field apiKey. Previously, generated keys started with k followed by 64 random ASCII letters and digits (65 characters total). New keys start with kt_ followed by the same 64-character random payload (67 characters total). The payload still includes both uppercase and lowercase letters. Keys remain case-sensitive. The request and all other response fields are unchanged. Included in release 2026-09-28.
Customer action
Allow the underscore and the new total length in fields and validators that consume generated keys. Preserve the exact value returned by the API, including the prefix. Prefer treating keys as opaque strings. Do not add or replace a prefix on existing keys: their stored hashes and login behavior are unchanged. Both existing keys and new kt_ keys remain usable with Equipment service login until replaced or revoked. Client packages were rebuilt for release 2026-09-28.
Release 2026-09-28 · available on this host
SetServiceProfileField · ApiKeyHash no longer accepts manual writes
Affected: the field path parameter and the response to manual hash writes. Previously, ApiKeyHash accepted a caller-supplied hash, or an empty value to clear it, and returned HTTP 200 on success. Only Name and Icon are now accepted. Requests with field=ApiKeyHash return HTTP 400 with problem code invalid-service-profile, regardless of the supplied value. No hash is written or cleared. Included in release 2026-09-28.
Customer action
Remove manual hash editing and clearing. To replace a service key, read its latest profileRevision with GetService, then call GenerateServiceApiKey at POST /api/v1/services/{serviceKid}/api-key:
{"expectedRevision":"<profileRevision from GetService>"}
Use the returned apiKey only after a successful HTTP 200 response and keep details.profileRevision for later edits. Generation replaces the existing key; the plaintext key is returned once. Do not retry automatically after an uncertain response. Manual key import and clearing are no longer supported. Existing stored hashes and response shapes are unchanged. Client packages were rebuilt for release 2026-09-28.
Locations1 location directory
One bank: Both GetLocations and GetActiveLocationCount accept optional bankKid, a canonical bank KID in the site tenant. It intersects current grants before search, sorting and pagination; it never grants access or changes site-wide privileges. Example: GET /api/v1/locations?bankKid={bankKid}&fields=address&enabledOnly=true. Repeat the same bankKid with every cursor; changing it returns 400 invalid-cursor. Invalid or wrong-tenant bank KIDs return 400 invalid-bank. Omit it for the existing cross-bank view. Implemented locally, unreleased.
Filtered location count (unreleased)
GetLocationCount — GET /api/v1/locations/count returns {"count":123} for the complete filtered result. Use the same filter, fields, enabledOnly, bankKid, sort and direction as GetLocations. Selected fields affect search, even when they are empty in some rows. The operation reuses Locations1, Bank Read, Location Read, tenant/resource scope, retention, KID/code lookup and code-access validation. It counts all matching states allowed by those rules; it is not the active navigation badge. No cursor or pageSize applies.
Start counting in parallel with data retrieval. Keep progress unknown until count is available; never treat failure as zero. HTTP 400 means invalid options, 401 requires login, 403 means missing scope/permissions, and 503 locations-unavailable means storage failure or the 12-second deadline. No-store. Count is exact at query time, not a snapshot spanning later pages. Concurrent edits or permission changes may change the final total; do not show a false 100%. Cancel a pending count when retrieval finishes. This endpoint is locally implemented and unreleased; generated clients/packages remain deferred to beta preparation.
Filtered export counts for every directory
Excel export starts at 100 rows and adapts each subsequent page between 10 and 250 rows using measured API response time, targeting 2.5 seconds. Each data request has a 3-second cancellation timeout. A timed-out read retries the same cursor with half as many rows; if the minimum size also times out, the export fails without publishing a partial workbook. Private directory pageSize may change with a cursor; all filters, sorting, selected fields and scope must stay unchanged. The separate count request retains its own deadline. Normal list defaults and balance batch limits are unchanged. Existing unit/terminal cursors created before this update require restarting without a cursor (400 invalid-cursor). Unreleased.
These endpoints return {"count":123} for the complete authorized export selection. Send the same filter, sort, direction as the listing; banks and units/terminals also accept enabledOnly, fields; banks accept bankType; units/terminals accept locationKid, terminalKid, runningOnly (units also autoOutOfOrderOnly); installers accept includeActivationCode; resident search accepts enabledOnly; bank residents accept locationKid, deleted. Do not send a cursor .
Every count rechecks the listing authorization, scope, retention and filters. Banks, locations and units/terminals use direct SQL aggregates. Resident search counts whole-bank access in SQL; location-only grants stream only identity/access data through the shared legacy/JSON Locations decoder, without details or page enumeration. Administrators, installers and bank residents count one minimal filtered index (existing indexes may be up to 60 seconds old); services use their finite catalog. Existing storage deadlines and bounds still return 503 instead of partial counts. Start count concurrently with retrieval, show fetched rows while pending/failed, then switch to percentage. HTTP 400 means invalid options, 401 requires login and 403 means missing access. No-store. No snapshot spans subsequent pages, so concurrent edits can invalidate a count. Navigation badges retain their distinct semantics. Locally implemented, unreleased; clients/packages follow at beta preparation.
Active location count
GetActiveLocationCount — GET /api/v1/locations/active-count. Returns {"count":123} for the Lokationer/Locations1 icon. Uses the same active-manager, Locations1, Bank Read, Location Read and site/bank/location authorization as GetLocations. Counts only distinct locations with Enabled exactly 1 and Deleted=0, also for all-bank managers. Missing Deleted means zero; missing/invalid Enabled or malformed Deleted are excluded. Limited grants still require a parent bank visible under RetentionDays. Independent of search and paging; banks below 1000 are excluded. The aggregate is read afresh for each request, with permission snapshots at most 60 seconds old. No-store. 401 requires login; 403 means missing tab, read rights or resource access; 503 locations-unavailable means unavailable storage or a 12-second deadline—retry manually and never present it as zero. The portal loads the count in the background after displaying navigation, without delaying the page; it makes one request per navigation element and does not poll. Failed requests leave the badge absent; the icon badge and tooltip show the full count; the white capsule widens to fit the digits.
GetLocations — GET /api/v1/locations lists accessible locations across banks. Requires active manager, Locations1 (65), Bank Read, Location Read and matching site/bank/location grants, rechecked on every page. Location-only grants never expose siblings. With an explicit site-wide grant, all location states are listed, including disabled locations and old deletions; parent-bank deletion does not hide them. With limited grants, only locations whose Enabled value is exactly 1 are listed, and both bank and location deletion follow RetentionDays. Missing Enabled is not enabled. Deleted=0 or missing is visible; positive timestamps must fall within the inclusive window from now minus RetentionDays through now. Zero retention hides all deleted entries; malformed or future deletion values are hidden for limited grants. Reads only site Log24; banks below 1000 are excluded. Discovery requires a Name, Icon, VismaCustNo, Enabled or Deleted location setting.
enabledOnly=true excludes locations whose Enabled value is not exactly 1, before paging. The default is false. This only narrows the authorized results: existing deletion/RetentionDays rules and activation-code permissions still apply. Enabled deleted locations remain visible when authorized. Keep this value on every continuation request; changing it requires restarting without a cursor (otherwise 400 invalid-cursor). Example: GET /api/v1/locations?enabledOnly=true&sort=name&direction=asc&pageSize=50.
Selected columns:fields is a comma-separated list of bankName,vismaCustNo,bankActivationCode,locationActivationCode,address,zip,longitude,latitude,teltonikaSms,alternativeBankName,mask,timeZone,online,lastContactAt. Omitted or empty means identifiers, status, names and icons only; unselected item properties are null. The response fields array contains the normalized requested selection. Location-owned address and zip are strings (empty when missing), without bank inheritance; longitude and latitude are nullable decimal degrees, converted from stored microdegrees, null when missing, malformed or outside ±180/±90. Only requested settings are joined; external ID may still be read internally for search/sorting. Selecting activation codes never bypasses the existing site-wide grant and Create permissions. Example: GET /api/v1/locations?fields=vismaCustNo,address,zip,longitude,latitude&enabledOnly=true&pageSize=50. Keep the same selection on every continuation; order and duplicate names do not matter. Unknown names return 400 invalid-fields; changed selections return 400 invalid-cursor, so restart without a cursor. The portal immediately reloads the list when a column checkbox changes in its side panel and remembers the selection in this browser and the page URL; KIDs remain API identities but are no longer displayed as a list column.
Map coordinates:includeCoordinates=true additionally returns latitude and longitude without adding these columns to text search or changing the response fields selection. Default: false. Example: GET /api/v1/locations?fields=address&filter=street&includeCoordinates=true. The same location permissions and nullable decimal-degree rules apply. Keep this option unchanged with each cursor; changing it returns 400 invalid-cursor, so restart without the cursor. Follow all pages; locations without valid coordinates cannot be plotted.
The additional optional columns teltonikaSms, alternativeBankName, mask and timeZone read the location-owned eSetting.TeltonikaSMS, eSetting.Bank, eSetting.Access and eSetting.TimeZone from Log24. They are strings: selected missing values are empty, unselected values are null. Phone prefixes, mask syntax and the legacy time-zone representation are preserved (for example 100 means UTC+1); this is not an IANA time-zone ID or a calculated current daylight-saving offset. No bank inheritance or interpretation of masks as API permissions. Example: GET /api/v1/locations?fields=teltonikaSms,alternativeBankName,mask,timeZone&pageSize=50.
Additional billing columns and sort keys: vismaCrAcNo, vismaInvoiceVersion, vismaOrdre, vismaPNTurnover, vismaPNSettlement, vismaSettlement, vismaVAT, vismaServiceKey, vismaStart, vismaNote, hiddenNote, vismaGuaranteeMonth, vismaGuaranteeUnder, vismaGuarantee, vismaGuaranteeCustomer, vismaGuaranteeOver, gift, giftBegin, giftEnd, giftSplit, giftPN, soapEnd. Each reads the identically named eSetting from the location’s Log24, without bank inheritance. Values are stored strings: selected missing values are empty, unselected values are null. Gift and giftBegin/giftEnd sort numerically; other billing fields sort as stored text (including percentages and legacy date strings). Gift is stored in hundredths; giftBegin/giftEnd are milliseconds since 2000-01-01 UTC. The portal formats the gift amount and these dates for display. Mixed amounts and percentages are preserved without conversion. giftPN reads legacy location setting 1620, named DurationIsETA in the shared enum for unit settings; it is the welcome-gift item number, not an ETA flag. soapEnd reads the saved date text from location-owned eSetting.SoapEnd (3025), like vismaStart; it is not MS2000. It sorts as stored text and is displayed unchanged, with missing values blank and unselected values null. Select it with GET /api/v1/locations?fields=soapEnd&sort=soapEnd; existing manager, scope, retention and cursor rules apply. Implemented locally, unreleased. The existing vismaCustNo and zip fields provide customer number and postal code.
The optional bankName selection shows the bank name and bank icon together after the location in the portal. Core bank identity properties remain populated in the API response.
Text filtering searches names and external ID plus every selected stored column before paging. Unselected extra fields do not match, even when used for sorting. Coordinates and gift amounts also accept their decimal representation with a dot or comma; gift/contact dates accept ISO dates and dd.MM.yyyy or dd-MM-yyyy (UTC for contact times). Online accepts online/offline or 1/0. Exact KID and full activation-code matching keep their existing authorization rules.
Optional online and lastContactAt read only the trusted tenant’s Alive table, for the exact authorized location’s Log24-discovered units within RetentionDays. Only main-unit rows with Alive.UnitId = Alive.MainId contribute; child units are excluded. Online is false if any visible main unit has Offline=1, true only for a nonempty set entirely Offline=0, otherwise null. LastContactAt is the latest valid MS2000 greater than zero and not in the future, returned as UTC ISO 8601; absent contacts are null. It is last contact, not the last machine run. Orphan Alive rows do not contribute. Both fields stay null and Alive is not read when neither selected nor sorted. sort=online orders unknown/offline/online ascending; sort=lastContactAt orders chronologically, unknown first ascending and last descending. Example: GET /api/v1/locations?fields=online,lastContactAt&sort=lastContactAt&direction=desc&pageSize=50. Existing authorization and cursor rules apply. The portal shows contact times in the browser’s time zone.
items contains kid (location), bankKid, bankName, bankIconKid, name, iconKid, vismaCustNo, bankActivationCode, locationActivationCode, enabled, deleted and deletedAt. Enabled is true only for stored 1. Deleted is false for zero/missing, true for positive MS2000, and null for malformed values. DeletedAt is an ISO 8601 UTC timestamp, or null for zero/invalid/out-of-range values. Use accessible status indicators for disabled, deleted and unknown deletion states. The portal uses one status icon: Enabled=false always means inactive; Enabled=true with Deleted=true means deleted, otherwise active when Deleted=false. The deletion timestamp remains available in the tooltip. These list rules do not change authorization on detail endpoints. KIDs are canonical; no separate numeric identifiers. Missing names/customer numbers are empty strings; invalid icons use bank_building/house. The page-level hasAllBanksAccess flag indicates an explicit site-wide grant, not an enumeration of individual banks. Both codes require this grant; bank codes additionally require Bank Create and location codes require Location Create. Otherwise the code is null. Hide both code columns when the flag is false. These fields never grant API permission.
Optional filter: up to 128 characters, literal case/accent-insensitive substring of bank/location name or VismaCustNo. Exact canonical, readable or site-relative bank/location KIDs are accepted, e.g. 166.2000.4 or 2000.4. Complete activation codes match only if the caller may view the code. Bank codes contain tenant; location codes use the trusted site. No cross-tenant reads.
sort: name (default), bankName, vismaCustNo, address, zip, longitude, latitude, teltonikaSms, alternativeBankName, mask, timeZone, online, lastContactAt, bankActivationCode or locationActivationCode. direction=asc (default) or desc. All sorting applies to the complete authorized matching result, not only the loaded page. Coordinates and legacy time-zone values sort numerically; missing/invalid numeric values come first ascending and last descending. Postal codes, phone values, masks, names and external IDs use utf8mb4_general_ci text ordering before SQL LIMIT. Code sorts use numeric FlexActivation codes and require the corresponding site-wide/Create access, otherwise 403 missing-code-access. They stream all authorized matches while retaining at most pageSize+1 candidates; narrow the filter for large result sets to avoid the existing 12-second deadline. Numeric bank/location IDs break ties in the same direction. The sort setting is read even when not selected as a returned column. Example: GET /api/v1/locations?fields=zip,address&sort=zip&direction=asc&pageSize=50. Page size is 1–100, default 50; continue with unchanged parameters and nextCursor until null. Cursors expire after 15 minutes and bind caller, tenant, grants, retention and query. Restart without cursor when these change. No total count or full in-memory catalogue; concurrent renames may move rows.
400: invalid-page, invalid-filter, invalid-sort, invalid-cursor (restart). 401: sign in again. 403: missing-banks-tab, missing-bank-read, missing-location-read, missing-resource-access (correct permissions). 503 locations-unavailable includes the 12-second deadline: show error and allow manual retry. Responses are no-store. Read-only; available in development. Generated clients and downloadable packages are synchronized in version 0.4.2.
Resident number suggestions
GetBankUserNumberForNewUser: GET /api/v1/banks/{bankKid}/users/next-number uses the bank's first NumberFormats entry and stored NumberFormatUserIndex (default 1). GetBankNextUserNumber: GET /api/v1/banks/{bankKid}/users/next-number-after?userNumber=1420-01-0004 starts from the supplied number instead.
Both require a valid manager bearer session, Users2, User Read, User Create and a bank-wide grant. A location-only grant is insufficient. Tenant binding comes from the site; bankKid must be its canonical bank KID. These read-only operations do not reserve a number or update the index. They use the existing FlexOrm conversion, including segment increments and wraparound, testing up to nine candidates. Active occupied numbers are skipped; creation still rechecks uniqueness in its transaction. An empty number means missing configuration or no available candidate within that bounded search, not necessarily exhaustion of the whole format.
curl -H "Authorization: Bearer $TOKEN" "$API_BASE/api/v1/banks/$BANK_KID/users/next-number"
curl -G -H "Authorization: Bearer $TOKEN" --data-urlencode "userNumber=1420-01-0004" "$API_BASE/api/v1/banks/$BANK_KID/users/next-number-after"
// Example response (illustrative bank and number):
{"bankKid":"A6Q14o58Cb","number":"1420-01-0005"}
400: invalid bank or number-format (the supplied number must match segment lengths and ranges); 401: invalid session; 403: insufficient access; 503: unavailable storage or malformed stored settings, including number-format-unavailable. Handle a failed request separately from an empty suggestion. Responses are no-store. The official portal fetches the suggestion only when its side-panel card becomes visible. New operations; not yet released.
Create an administrator
Unreleased:CreateManager, POST /api/v1/managers, has no request body. Requires Managers1, independent Managers Read and Create, and a whole-tenant grant. Write alone does not grant Create. The actor's account, credential stamp and permissions are read afresh before allocation and again inside the write transaction, with locks held through commit. The site determines the tenant.
The Location response header points to GetManager. The new administrator is enabled and not deleted, with no assigned password, email, tabs or scopes. No invitation is sent. Use GetManager and the existing profile, permission, scope and tab operations to configure it; these edits have their own authorization requirements, including Managers Write.
Allocation finds the next never-used manager ID above the greatest ID in history/current Log7 and atomically appends Enabled=1 and Icon=businessperson. The new administrator starts with the businessperson icon; existing administrators keep their stored icons. No Deleted setting is written; deleted IDs and abandoned reservation markers are never reused. A tenant-specific MySQL advisory lock is acquired before allocation and held through commit on the same writer connection. Waiting for the lock is limited to five seconds within the 15-second operation deadline; failure to acquire it returns 503 without creating a manager. No table lock, schema change or random marker is used. All creators, including AMS and FRA, must use the same lock on the same MySQL writer. Independent writers are not supported by this lock; modulo allocation by ServerId, using a fixed common modulus and a unique residue per writer, is the agreed future approach if needed and is not implemented yet.
401: log in again. 403: missing-managers-tab, missing-managers-read, missing-managers-create or missing-tenant-access; obtain the required access. 409: manager-ids-exhausted (identity range exhausted). 503: manager-creation-unavailable. Application errors use ProblemDetails with code; 401 can have no body. Creation is not idempotent: after a timeout, cancellation or lost response, inspect the directory before a manual retry. Never automatically resubmit creation.
Gravatar
Administrator avatars: GetManagers, GetManager and SetManagerProfileField include nullable gravatarUrl. Gravatar is preferred; the stored icon, or the standard person icon when none is selected, is the fallback. When Email is valid, the API returns https://www.gravatar.com/avatar/{sha256}?s=96&d=404&r=g, using the trimmed, lowercase email. Render it as an image with referrerpolicy="no-referrer"; on 404 or network failure use iconKid instead. Null means use iconKid directly. Refresh the avatar after Email or Icon changes. This is a presentation hint, not proof of identity. Direct browser requests disclose the email hash and client IP to Gravatar. No Gravatar account, API key, profile lookup or database write is required. The portal uses this fallback in administrator lists, detail headings and workspace shortcuts. Unreleased; packaged clients are updated during beta preparation.
GetManagersWithSameEmail
GetManagersWithSameEmail: GET /api/v1/managers/{managerKid}/same-email returns [{"kid":"canonical manager KID","name":"display name"}]. Requires the same active session, Managers1, Managers Read and whole-tenant access as GetManager. The source must be visible (otherwise 404). Matches use exact trimmed email, ignoring case; empty emails and the source are excluded. Disabled managers remain eligible, deleted managers follow caller retention. The candidate index can be 60 seconds old; matching candidates are reread from current Log7. Maximum 100 candidates, 20,000 indexed entries and a 12-second deadline; larger results fail with 503 manager-directory-too-large, never a truncated list. 400 invalid-manager-kid, 401 login required, 403 missing access, 503 managers-unavailable for storage failure. Responses use no-store. Example: curl -H "Authorization: Bearer $TOKEN" "$API_BASE/api/v1/managers/$MANAGER_KID/same-email". The portal fetches the list only when the side panel is visible, shows links only when matches exist, and invalidates the list after saving Email or navigating to a manager. Refresh waits until the panel is visible. Unreleased; generated clients follow at beta. Each match also includes iconKid and nullable gravatarUrl: show Gravatar first, then the icon, or the standard person icon when unset.
Bank directory and account currency icon
List authorized banks and render the most frequent authorized ledger currency in the account icon.
GetBanks: GET /api/v1/banks and GetActiveBankCount: GET /api/v1/banks/active-count require Banks2 (5), Bank Read and site grants. Core values: kid, name, iconKid, enabled, deleted, deletedAt. Optional fields=bankType,bankActivationCode,exportFormat,settlementEmails,settlementDays,bankDays,cluster,hardware are returned in each item's fields dictionary; the response fields array lists the selected keys. BankDays and SettlementDays are separate stored settings. Bank-wide metadata requires whole-bank or whole-tenant access; location-only grants expose parent identity and null optional values. Bank activation code display/search/sort additionally requires whole-tenant access and Bank Create. Location activation codes remain separate in GetLocations.The response canReadBankActivationCode boolean indicates whether the caller may use bank codes.
filter (0–128 characters) searches name and authorized settings, or an exact bank KID/activation code. Optional bankType=Credit|Cash adds an exact type match to the text search, so localized clients can match their translated label without losing text matches. sort accepts name (default) or any optional field key; direction asc/desc. Stored settings sort as text; activation codes sort numerically with FlexActivation. Code sorting streams the authorized matches and retains only pageSize+1 rows; narrow the filter if the 12-second deadline is exceeded. pageSize 1–250, default 50. Keep all options unchanged with nextCursor (15-minute expiry, bound to manager and scope). Concurrent changes can move rows. Site-wide access may include all states; limited scope requires Enabled=1 and deletion within RetentionDays. enabledOnly=true and active-count require Enabled=1 and Deleted=0; missing Deleted means zero. No map. New optional fields are unreleased; clients are synchronized at beta.
GetBankAccountIcon: GET /api/v1/banks/{bankKid}/account/icon. Requires Account2 and Bank, Location, Unit and User Read. Counts all Log1 rows across periods in the authorized location scope, independent of amounts and current account filters. Trimmed three-letter codes are uppercased; invalid/blank codes are ignored. Highest row count wins; alphabetical currency breaks ties. Returns currency (null for empty data) and iconKid with the currency in its text. Render iconKid unchanged through GetIconFromSet.
GET /api/v1/banks?pageSize=50&sort=name&direction=asc&enabledOnly=true
Authorization: Bearer YOUR_MANAGER_TOKEN
GET /api/v1/banks/{bankKid}/account/icon
Authorization: Bearer YOUR_MANAGER_TOKEN
Use the existing manager bearer session. All reads are no-store. 400 means invalid input/cursor (restart pagination); 401 requires a new session; 403 requires the appropriate tab/read/scope grants; 503 is temporary storage failure (retry manually). These new endpoints are implemented locally and unreleased.
Resident directory — UserFinder1 (77)
GetUsers: GET /api/v1/users lists residents across the manager's authorized banks and locations. Requires UserFinder1, User Read and matching resource grants. The trusted site selects the tenant. Current Log7 data and RetentionDays determine visibility; location-limited managers see only associated residents. No legacy business tables are read.
GET /api/v1/users?pageSize=50&sort=identity&direction=asc&enabledOnly=true&filter=Alice
Authorization: Bearer {managerToken}
filter accepts 0–128 characters: literal name/number substrings, exact email/SMS, or a complete resident KID. sort is identity (default; numeric bank/user order), name or number; name/number sorting scans the full authorized candidate set and can be slower; direction is asc or desc. enabledOnly=true means not deleted (residents have no Enabled setting). Items contain kid, bankKid, name, number, iconKid and nullable deletedAt. Open an item using GetBankUsers with its bankKid and exact userKid; that single-resident read accepts UserFinder1. Bulk bank lists and all existing write/activation/balance operations keep their own Users2 and operation requirements.
Follow nextCursor with unchanged options and pageSize (1–250). Cursors expire in 15 minutes and are bound to manager, site, scope and query. A scanLimitReached page can be empty; continue when nextCursor is present. At most 1,000 candidates per call; no total count. Concurrent edits can move records between pages. Do not cache results or log personal search text. Handle 400 by restarting the query, 401 by renewing the session, 403 as a permission denial, and 503 with a user-initiated retry.
Administrator and installer counts
GetManagerCount: GET /api/v1/managers/count requires Managers1 (28), Managers Read and whole-tenant access. GetInstallerCount: GET /api/v1/installers/count requires Installers1 (68), Installer Read and whole-tenant access. Both recheck the active manager session and return {"count":123,"iconKid":"canonical icon KID"}. Counts cover all visible identities, independently of filters and paging, including disabled accounts and deletions within the caller's RetentionDays. Existing directory indexes may be 60 seconds old. The administrator index is bounded to 20,000 identities; installers to their 999-identity range. Exceeding a bound returns 503, never an estimate or partial count. No resident total is exposed.
401: renew the session; 403: check tab, Read and scope; 503: allow a manual retry. No-store. Fetch asynchronously when the navigation item becomes visible. Unreleased; generated clients follow at beta.
Service count
GetServiceCount: GET /api/v1/services/count returns count and iconKid for the unfiltered GetServices catalog. Same active session, Services1, Service Read and whole-tenant grant. Counts the same distinct concrete eUserId definitions as GetServices, excluding range-end markers; no service settings or extra business SQL is read. Existing session authorization still applies. 401: renew session; 403: check permissions; 503: retry manually. No-store. Unreleased.
Starts more than 100 hours before the measurement time are excluded; exactly 100 hours is included.
Running machines
GetPublicRunningMachines — GET /api/v1/public/statistics/running-machines
No login or per-machine permission is required; only a tenant-wide count is public. The site selects the tenant. Counts distinct bank/location/unit identities in Log24 using the latest Started and Done state values (UTC milliseconds since 2000-01-01): Started < now and Done > now. Missing, malformed or conflicting values do not qualify. This time-window estimate does not check online status. Both success and failure are cached for 15 seconds per API instance; poll every 15 seconds. HTTP 503 with Retry-After: 15 means unavailable, never zero. Reads are capped at 100000 lifecycle rows; exceeding that limit returns 503. The response contains tenantKid, count, measuredAtUtc and refreshAfterSeconds (15). No identifiers for individual machines are returned.
GET /api/v1/public/statistics/running-units returns a tenant-bound array without paging, names or temperature. Each item contains unitKid, startedAtUtc, doneAtUtc, unitType and cycle; the last three may be null. The snapshot is cached for 15 seconds. Overflow or source failure returns HTTP 503 with Retry-After: 15 instead of a partial list. See the example.
Reservation count
GetPublicReservations: GET /api/v1/public/statistics/reservations. No login or parameters; the site selects the tenant. Returns tenantKid, count, measuredAtUtc and refreshAfterSeconds (60).
Counts dated reservations that have not ended, including ongoing reservations. Uses the current tenant Log5 snapshot, whose primary key is start/bank/location/unit/type. Here Text (start minutes) and Amount (duration minutes) are signed SQL INT NOT NULL columns, read as Int32; digit and length validation for bank Log5.Text string storage does not apply. This shared table has no Period column: its trigger replaces a row only when the incoming MS2000 is newer, including the negative Amount of a cancellation. Period=0 filtering applies to bank Log5 history, not this snapshot. Amount must be positive and local start plus duration must be after now. Cancelled, ended, AUT/isy auxiliary entries and weekly templates are excluded. Location time zone inherits from the bank, defaulting to Europe/Copenhagen when absent. Only an aggregate is public, without identities or permissions.
Poll every 60 seconds. HTTP 503 means unavailable, never zero; retry after 60 seconds. Conflicting time-zone revisions, invalid time zones and more than 100000 candidate rows also return 503.
Reserved machines
GetPublicReservedMachines — GET /api/v1/public/statistics/reserved-machines
Counts distinct machines with a dated reservation covering the current location-local time (start inclusive, end exclusive). Overlapping reservations for one bank/location/unit count once; future, ended, cancelled, weekly-template and AUT/isy entries are excluded. Time zones and bounded reads follow the reservation aggregate above. Host returns zero because it has no machines. No location, machine or resident identities are returned.
The display pool is a random sample of up to 1000 machines, started within 100 hours and ending within the next 3 hours. Larger eligible pools are sampled rather than rejected.
Numeric name placeholders such as [455] are resolved through Kombine.Flex.Localization using Accept-Language, after reading the shared raw cache.
Live machines
GetPublicLiveMachines: GET /api/v1/public/statistics/live-machines
Anonymous on every tenant site, using only its trusted configured tenant. The caller cannot select a tenant. Returns an array of unitKid, unitName, locationName, startedAtUtc, doneAtUtc and nullable temperature. Uses current Log24 Started < now < Done, eSetting.Name and eState.Temperature; no resident data. Missing or conflicting lifecycle values are excluded. Refresh every 60 seconds; select distinct random machines, retain running selections and count down locally each second. HTTP 503 means unavailable; retry after 60 seconds. Limited to 1000 running machines and 100000 source rows.
GET https://api.team.kombine.technology/api/v1/public/statistics/live-machines
Only currently running machines with a valid end time after now and no more than 3 hours ahead are eligible; stored Done values outside this window are excluded. The response schema still allows null for doneAtUtc; clients should not select entries without a valid end time in this window. Temperature is omitted visually when null. Up to 10000 additional metadata rows are read only for running machines and their locations.
ErrorUnit
Optional fields=errorUnit returns the last stored eState.ErrorUnit (331) as JSON text in items[].errorUnit. Empty string means absent; null means not selected. A recorded error may no longer be active. sort=errorUnit uses lexical stored-text ordering before pagination. Existing Units1, Bank/Location/Unit Read, scope and retention checks apply. Keep query options unchanged with nextCursor; 400: invalid fields/sort/cursor, 403: missing permission, 503: temporary unavailability. Unreleased; client packages are refreshed at beta.
GET /api/v1/units?fields=errorUnit&sort=errorUnit&direction=desc&pageSize=50
Authorization: Bearer YOUR_MANAGER_TOKEN
GetCameraNearestLocation — GET /api/v1/camera/nearest-location?latitude=55.7&longitude=12.5&accuracyMeters=5 selects the nearest enabled, retention-visible location within 100 metres. Coordinates are decimal degrees; accuracy is metres (0–100). Send a manager bearer token with Camera1 and Location Read/Write. Only trusted-tenant scoped locations qualify; bank/unit targets are excluded. The result uses CameraResourceResponse. 400: invalid position; 401/403: denied; 404: no eligible location; 409: the nearest two cannot be distinguished within twice GPS accuracy (minimum 1 metre); 503: timeout/storage failure or over 100 candidates. On 404/409, open the intended location manually. Normal prepare/upload authorization remains mandatory. No GPS position is persisted by this lookup.
GetRecentCameraPhotoMetadata — GET /api/v1/camera/recent/{id}/metadata reads the saved capture metadata for a recent public thumbnail. Copy the opaque id from the thumbnail URL returned by GetPublicRecentCameraPhotos and send a manager bearer token. Requires Camera1, resource Read, scope and retention visibility on every request; the public thumbnail token does not grant private access. Returns the same JSON metadata as GetCameraCaptureContent with part=metadata. 400 means an invalid or expired thumbnail token (refresh the public list); 401/403 means access denied; 404 means unavailable capture metadata; 503 means storage unavailable. Never expose this response publicly. The portal uses saved weather and orientation for hover information; missing indoor temperature is unknown, GPS travel direction is not camera heading.
GetCameraResource also returns requiresProximityCheck and nullable latitude/longitude in decimal degrees. Locations use their stored coordinates; units inherit their location coordinates. Banks return false and null coordinates. The portal warns before taking a photo or video when the measured distance exceeds 100 metres, or the distance is unknown (missing coordinates, denied GPS, a position older than 60 seconds, accuracy worse than 100 metres, or a failed lookup). Users can cancel or continue. Retrying an existing upload does not capture again. This advisory check does not grant or restrict API access.
Large JPEG metadata (unreleased fix): the original JPEG remains byte-for-byte unchanged. When raw metadata exceeds the 256 KiB duplication budget, or its JSON exceeds 512 KiB, embeddedMetadata.metadataExtraction is original-only: exif is null and attributes and embeddedBlocks are empty. embeddedBlockReferences retains each JPEG metadata payload as Kind, Offset and Length; offsets are zero-based byte positions in the original file and exclude marker and length bytes. Read that authorized original to recover the full metadata. Smaller JPEGs retain extracted metadata and report complete. The 32 MiB photo limit, pixel and segment-count limits, structural validation, and compressed PNG metadata limits still apply.
More specific JPEG diagnostics (unreleased): photo-pixel-limit, photo-metadata-limit, photo-metadata-block-limit, photo-jpeg-marker, photo-jpeg-truncated-marker, photo-jpeg-missing-frame, photo-jpeg-structure, photo-jpeg-truncated-segment, photo-jpeg-encoding, photo-jpeg-frame and photo-jpeg-missing-end. These distinguish resource limits from malformed or unsupported JPEG data; the HTTP status and error code remain unchanged.
Photo rejection diagnostics (unreleased): HTTP 422 retains invalid-camera-media. An optional ProblemDetails diagnostic identifies the failing stage: photo-size, photo-format, photo-jpeg-header, photo-png-header, photo-decode, photo-metadata or photo-thumbnail. It contains no image metadata or decoder messages; clients must tolerate a missing or unknown value.
Private camera captures (unreleased)
Camera1 uses the current manager's tenant, tab and resource permissions. Listing and media require resource Read; preparation and upload also require Write. The tenant list contains the manager's own captures; a resource list includes other authorized managers' captures on that exact bank, location or unit. Service accounts are not accepted.
GetCameraResource: GET /api/v1/camera/resource?resourceKid=KID returns resourceKid, name and iconKid for the exact authorized bank, location or unit. Use this for the local camera heading instead of loading a parent overview or child directory. It requires Camera1, that resource type's Read permission, scope and retention visibility; a location does not require Unit Read and a unit does not require Location Read. Units include only the inherited location coordinates, not other parent or child metadata. Pass iconKid unchanged to the icon API. Errors: 400 invalid/cross-tenant KID, 401 invalid session, 403 denied, 404 missing or outside retention, 503 unavailable lookup.
GET /api/v1/camera/resource?resourceKid=CANONICAL_RESOURCE_KID HTTP/1.1
Authorization: Bearer YOUR_MANAGER_TOKEN
GetCameraAvailability: GET /api/v1/camera/availability?resourceKid=KID returns hasCaptures, isDegraded and canCapture for lazy navigation. GetCameraCaptures: GET /api/v1/camera?resourceKid=KID&cursor=TOKEN returns items, nextCursor and isDegraded. Omit resourceKid for own captures. Follow the opaque nextCursor with the same scope, including empty filtered pages. Both private regional indexes are queried and deduplicated; degraded results may be incomplete and must be refreshed from the beginning after recovery.
GetCameraCaptures items also include nullable bankName, locationName and unitName (unreleased). These are current display names, not names frozen at capture time. Each name requires that object's Read permission, resource scope and retention visibility; inapplicable or unauthorized names are null. Unit names resolve localized placeholders. Clients may display the available names in bank/location/unit order and must continue using resourceKid for identity and navigation.
Browser file imports use the same prepare/upload operations and permissions. capturedAtUtc accepts dates from 1970-01-01 UTC through five minutes ahead of server time (unreleased). When the capture time is unknown, clients may use file last-modified time or upload time and declare the source in sensorData.timestampSource. Do not attach current device sensors to historical media. The portal file picker supports JPEG/PNG up to 32 MiB and MP4/MOV/WebM up to 128 MiB; the server validates the original media.
For file imports, resolve the target with GetCameraNearestLocation using embedded EXIF GPS (JPEG/PNG) or QuickTime location metadata (MOV/MP4), not the uploading device’s current position. The portal uses a conservative 100-metre accuracy window when metadata does not specify accuracy; missing, invalid or ambiguous geodata stops the import without uploading. Files retain their original bytes. The separate /camera/upload page does not open the camera or microphone.
When upload is opened from a location or unit, the portal uses that explicitly selected, API-authorized resource. GPS is optional in this case. A distance greater than 100 metres from its location coordinates produces a confirmation warning; declining skips only that file. Tenant-level uploads still resolve their target from embedded GPS.
PrepareCameraCapture: POST /api/v1/camera/prepare accepts the JSON below. Hash the original bytes with SHA-256. Retain the returned uploadToken for retries: it binds the authenticated owner, resource, original hash and metadata, including optional weather, for 24 hours. SaveCameraCapture: POST /api/v1/camera accepts multipart uploadToken and original (binary file). Success confirms media, generated thumbnail and matching JSON in one region; the second copy continues independently of navigation. There is no success notification requirement.
After an uncertain upload response (for example HTTP 504), call ConfirmCameraCapture with the original ticket. This operation requires the same authenticated owner and current Camera1/resource Read and Write. Only confirmed: true confirms publication of the exact capture; false or a 503 response does not prove failure. Keep the original bytes and ticket for a later retry; do not create a new plan automatically. Invalid/expired tickets return 400; missing authentication returns 401 and revoked access returns 403/404. This confirmation operation is unreleased; generated clients will be refreshed at the next beta release.
Optional ?background=true on SaveCameraCapture returns HTTP 202 after validating and staging the original bytes. This is not a durable save acknowledgment. Poll ConfirmCameraCapture with short requests until confirmed=true. Processing continues independently of the upload connection. The bounded processing queue is temporary: after restart or an unconfirmed result, retain the original and retry the same ticket. A confirmation errorCode of camera-processing-failed indicates that this instance stopped processing; retry is permitted. Default requests retain the synchronous 200 behavior.
The optional processingPercent field is a weighted estimate based on completed processing stages, not elapsed time or a time-remaining prediction. Values 0–99 represent temporary progress on the processing instance; null means unknown (for example another instance or a restart). Only confirmed=true returns 100. Clients must never infer successful storage from a progress value alone.
POST /api/v1/camera/confirmation
Authorization: Bearer YOUR_MANAGER_TOKEN
Content-Type: application/json
{"uploadToken":"ORIGINAL_UPLOAD_TOKEN"}
POST /api/v1/camera/prepare
Authorization: Bearer YOUR_MANAGER_TOKEN
Content-Type: application/json
{"resourceKid":"CANONICAL_RESOURCE_KID","kind":"photo","originalFileName":"IMG_1234.jpg","originalNameAvailable":true,"capturedAtUtc":"2026-10-15T08:00:00Z","mediaLength":12345,"mediaSha256":"SHA256_OF_ORIGINAL_BYTES","sensorData":{}}
GetCameraCaptureContent: GET /api/v1/camera/{id}/content?part=thumbnail streams through the authorized API. Obtain id from the list; identities expire after 30 minutes. Parts: original, metadata, thumbnail, preview, motion, motion-playback and playback when present. List items expose hasPreview, hasMotion and hasPlayback. For a video with hasPlayback=true, use part=playback; otherwise use original. Live Photos use original for the still and motion-playback for motion; motion retains the original MOV. Single byte ranges are supported for playback. No Spaces credentials, direct or signed storage URLs are returned.
Current capture support: JPEG/PNG photos up to 32 MiB and MP4/WebM/QuickTime MOV videos with audio up to 128 MiB, with a 60-second browser stop and a 61-second server ceiling for recorder completion. Each preview is 512 square; video previews contain three silent frames. Native live-photo uploads use a JPEG still (32 MiB maximum) plus its original QuickTime MOV companion (32 MiB maximum, at most 10 seconds). Prepare with kind=live-photo and additional motionLength and motionSha256 fields; upload both original and motion multipart files with the same uploadToken. Both components are hashed and decoded before publication. The thumbnail is static; no animated preview is generated for Live Photos. Ordinary QuickTime MOV and WebM videos retain their original bytes and have a separate H.264/AAC MP4 playback derivative for clients that cannot play those formats directly. Live Photo motion likewise keeps its original MOV and has a separate MP4 derivative, without invented audio when the motion original is silent. The complete regional set includes this derivative before publication. Native capture still requires platform/device verification; Android OEM Motion Photo integration is not claimed. Video requires configured ffmpeg/ffprobe on the API host. Original bytes are preserved. New capture filenames use a GUID and the media extension, without region labels or the device filename (unreleased). Related files retain suffixes such as .thumbnail.jpg and .json. The original device filename and origin remain in JSON metadata. Existing captures keep their names and remain readable. Treat returned filenames as opaque; the filename GUID is not the capture ID. Copies keep their origin name. Conditional object creation prevents overwriting distinct bytes; no camera database is used.
400: malformed KID, token, metadata or hash; 401/403: session/access; 404: missing resource/component; 413: size limit; 416: invalid range; 422: unsupported/invalid media; 429: capture processing busy; 503: storage or required processor unavailable. Retry the same capture with its retained uploadToken and original bytes. Missing sensors/weather remain explicitly unavailable and do not invent measurements. Interrupted replication and rare competing origin manifests for the same retried capture require later reconciliation; one surviving copy remains readable. No deletion, gallery import or automatic historical-weather repair is implemented.
Checklist1: settlement control
Unreleased; alfa preview.GetChecklist — GET /api/v1/settlement-checklist returns a bounded settlement checklist. GetChecklistPeriod — GET /api/v1/settlement-checklist/{periodKid} reads one current period. Both require an active manager, Checklist1 (10), Bank Read, Location Read and same-site resource grants. A location grant never exposes a bank-wide row. The trusted site selects the tenant; use canonical KIDs returned by the API.
The explicitly authorized read-only source is the tenant's existing Periods table. Names, hardware, enabled state and deletion visibility come from Log24. Both bank and location must be Log24-discovered and visible under RetentionDays. Missing Enabled defaults to enabled; disabled or malformed settings are excluded. Banks below 1000 are excluded.
The window is the latest bank period number and its two numeric predecessors. By default, Hide=255 and rows whose four codes are all 3 or 64 are excluded. Bank-wide rows additionally require the latest period and a due or unknown schedule. includeResolved=true also includes completed, hidden, scheduled and previous bank rows within this window; it never expands resource access or retention. Optional scopeKid is a bank or location KID, not a tenant KID. Omit it to list all granted resources.
The response is {items,nextCursor,readAtUtc}. Items contain kid,bankKid,locationKid,period,isLatest,bankName,locationName,hardware,periodDateUtc,nextSettlementUtc,lastRunUtc,updatedAtUtc,hidden,onChecklist,scheduleStatus,processing. Bank-wide rows have null locationKid/locationName/processing; scheduleStatus is Unknown, Scheduled, Due or Overdue (more than one day overdue). Location rows have null scheduleStatus and four independent {code,state} objects: invoice, soapInvoice, soapCredit and easyPay.
Processing codes: 0 Waiting, 1 Created, 3 Completed, 8 Failed, 16 Recreating, 32 NoData, 64 NotRequired. Unknown codes retain their number with null state; a missing code remains null. NoData and unknown states still require attention. Dates are UTC instants; zero/invalid dates become null. periodDateUtc is the stored boundary, without DatPro2's display subtraction of one second.
pageSize is 1–100 (default 50); order is bank/location/period ascending. Follow nextCursor unchanged with identical filters, size and Accept-Language. Cursors expire after 15 minutes and bind manager credentials, grants and retention. Each page reauthorizes. Concurrent changes can affect pages; refresh from the first page for a new view.
400: invalid KID/query/cursor; 401: invalid session; 403: missing Tab/Read/resource grant; 404: detail absent, invisible, disabled or outside the window; 503: storage unavailable. Renew an expired session; refresh on an expired cursor. Preserve and label stale results on 503; never interpret a failed read as an empty checklist. Responses are no-store.
Read only: no restart, recreation, hide action or invoice job enqueueing. No amounts, residents, job payloads or credentials are returned. Interactive example / single-file download includes bank search, optional scope, pagination, status details, print and synthetic demo. It reuses the exact-origin example session; the API key is never stored. For localhost setup see the example's help.
GET /api/v1/settlement-checklist?pageSize=50&includeResolved=false
Authorization: Bearer YOUR_MANAGER_TOKEN
Accept-Language: en-GB
GET /api/v1/settlement-checklist?scopeKid=CANONICAL_BANK_OR_LOCATION_KID&pageSize=50
Authorization: Bearer YOUR_MANAGER_TOKEN
GET /api/v1/settlement-checklist/CANONICAL_PERIOD_KID
Authorization: Bearer YOUR_MANAGER_TOKEN
Machine timeline (Datpro2 Offline3 Zoom)
Read-only, unreleased. The single-file machine timeline combines authorized Log0–Log6 events for one canonical machine KID. The existing shared manager login is reused. It includes UTC interval navigation, category/field filters, search across loaded pages, optional visible-page refresh, and authenticated WashDoc graph/measurement viewing.
GetUnitTimelineFields — GET /api/v1/units/{unitKid}/timeline/fields GetUnitTimeline — GET /api/v1/units/{unitKid}/timeline
Both operations require Offline3 (32), Bank/Location/Unit Read, matching tenant/bank/location grants and retention-visible Log24 bank, location and unit. Tags/Messages additionally require Users2; Transactions require Account2; Reservation requires Bookings1. These personal categories need User Read and a whole-bank or tenant grant. Text diagnostics require all three personal-data tabs. Without them only numeric/boolean technical values are exposed. Personal rows omit missing or retention-hidden residents, and obey both accounting and surveillance windows. Credentials, Configuration, hidden/unbound settings, raw tags and identity-bearing synchronization/release fields are excluded. Opaque Tags/Messages text is redacted; transactions use the existing receipt decoder. Unknown types keep only the explicit diagnostic/measurement profile. Document requests independently require WashDoc1/2/3.
Supply both fromUtc (inclusive) and untilUtc (exclusive), using UTC ISO timestamps, or omit both for the last six hours. Maximum interval: 24 hours; pageSize: 1–200, default 100. sources is a comma-separated list of exact names returned by the fields operation. field selects a setting/state enum name; other categories remain included unless sources excludes them. Follow nextCursor unchanged with identical query options. Cursors expire after 15 minutes and bind manager credentials, current permissions, unit type and privacy policy. Late arrivals and Sync updates require a refresh; pages are not an immutable export.
context contains the machine labels, type, permitted sources/fields and capabilities. items contain eventKey (unit-local timestamp/source key), source, exact decimal-string ms2000 and amount, timestampUtc, sync, field, currency, text, contentStatus, period, userKid and documentKid. Only sync=1 means acknowledged. Amount is the field ID for Settings/Live/States and minor currency units for Transactions. contentStatus=redacted distinguishes withheld data from a stored null. Preserve exact integer strings. There are no writes or messages. 400: invalid query/cursor; 401: sign in; 403: denied source or permission; 404: hidden/missing unit; 503: storage/oversized data. Retain a failed view only as explicitly stale. Host serves the demo but no unit data. Client package generation remains deferred to beta.
auxiliaryValue exposes only the documented auxiliary value for Alive, Error, Started, Done, Door, Process and Cycle, never raw tag credentials. The explicit profile also includes historical WashDoc measurements and the observed Electrolux diagnostic fields.
Errors2: machine error history
Unreleased; alfa preview.GetBankErrors — GET /api/v1/banks/{bankKid}/errors reads Error events from the selected bank’s Log3 and Log4. Requires an active manager, Errors2 (17), Bank/Location/Unit Read and matching resource grants. The host determines the tenant; all identifiers are canonical KIDs. SearchBanks — GET /api/v1/search/banks?q=NAME resolves a bank with any current Tab and Bank Read, without requiring Banks2.
days: 1–70, default 10. level is cumulative: ALR; JAN adds janitor (default); ERR adds errors; WAR adds warnings; INF adds information. includeAcknowledged defaults false, excluding Period=1. pageSize: 1–100, default 50. Response: items, nextCursor, fromUtc, untilUtc. Follow nextCursor unchanged with identical filters, page size and Accept-Language. Cursors freeze the time window, expire 15 minutes after the first page and bind credentials, grants, retention and write capability. Every page reauthorizes. Order: location, unit, timestamp descending, source. All matches are pageable, without the legacy four-per-machine limit. Concurrent acknowledgement can remove rows; refresh from page one.
Current Log24 unit discovery and bank/location/unit deletion visibility apply using RetentionDays, independently of the 70-day history bound. Unit type uses only current original packed UnitType; missing/invalid stays null. Descriptions come from stored event text; the obsolete Errors_ catalogue and editor are excluded. Legacy text uses its first tab segment and packed TagId supplies only code/count. Structured data exposes only Id, Miele.Count and Miele/Electrolux.Text. Missing fields are null; raw payloads, residents, payments, TagId and editor identities are not exposed.
GetError — GET /api/v1/errors/{errorKid} reads one authorized event within 70 days, including acknowledged events and any severity. AcknowledgeError — POST /api/v1/errors/{errorKid}/acknowledge additionally requires Unit Write and current expectedRevision. It rechecks account, password/API-key stamp, Errors2, permissions, scope and visibility under transaction locks, then changes only Period to 1. Original time, text and UserId remain intact; no new acknowledgement editor/time is recorded. Response: the updated event, acknowledged=true, new revision and canAcknowledge=false. This does not repair, reset, restore or change machine state.
GET /api/v1/banks/BANK_KID/errors?days=10&level=JAN&pageSize=50
Authorization: Bearer SESSION_TOKEN
GET /api/v1/errors/ERROR_KID_FROM_LIST
Authorization: Bearer SESSION_TOKEN
POST /api/v1/errors/ERROR_KID_FROM_LIST/acknowledge
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json
{"expectedRevision":"COPY_THE_64_HEX_REVISION_FROM_THE_EVENT"}
400 invalid KID/filter/revision/cursor: fix input or restart paging. 401: sign in again. 403: check Errors2, Read, grants and Unit Write for acknowledgement. 404: absent, expired or invisible. 409 error-conflict: reload. 503 errors-unavailable: storage failure, never an empty success. After a timeout, lost response or 503 during POST, read the event before deciding whether to retry. Never replay POST automatically. All responses are no-store.
The single-file example shares the existing manager bearer login and never stores the API key. It includes bank search, filters, paging, details, local read-only printing, explicit acknowledgement and a synthetic demo. Serve locally on http://localhost:8080 or http://127.0.0.1:8080; only these local origins allow bearer requests, without cookies. Host supports demo only. Packaged clients are updated during beta preparation.
Unreleased.GetOutOfOrderUnits — GET /api/v1/units/out-of-service reproduces the DatPro2 OutOfOrder1 selection: current Log24 OutOfOrder values 1–255, including manual shutdown (1), automatic shutdown (2) and repair (3). Enabled (0) and malformed values are excluded. Unknown nonzero codes remain visible with status=null. Requires an active manager, OutOfOrder1 (59), Bank Read, Location Read, Unit Read and matching site/bank/location grants. Tenant comes exclusively from the API host.
Only enabled locations are included; disabled units remain included. Bank/location/unit deletion visibility uses RetentionDays. Original packed UnitType is decoded with (value >> 1) & 255; missing/invalid types and StartSMS_60/TimeSMS_61 are excluded. UnitType2 is ignored. This list does not require an AutoOutOfOrder error ID or use the public widget's ten-day window.
Response: items, nextCursor, refreshAfterSeconds=30. Each item has kid, bankKid, locationKid, bankName, locationName, unitName, unitType, outOfOrder, status, statusLabel, timestampUtc, changedBy, revision, canRestore. Identities are canonical KIDs. status is a stable enum name or null; statusLabel and object names follow Accept-Language. changedBy contains display-only audit data (kid, kind, name, iconKid), not account permissions. timestampUtc is the OutOfOrder setting's timestamp. pageSize is 1–100 (default 50). Follow all cursors unchanged with the same pageSize and language. Cursors expire after 15 minutes and bind tenant, manager, credentials, rights, scope and retention. There is no total-result cap; ordering is timestamp descending, then numeric bank/location/unit. Concurrent changes can move rows. Refresh from page one every 30 seconds while visible.
RestoreOutOfOrderUnit — POST /api/v1/units/{unitKid}/out-of-service/restore additionally requires Unit Write. Send the current item's expectedRevision. The transaction rechecks account, credentials, OutOfOrder1, Read/Write rights, grants, retention, enabled location and original type under database locks, writes only OutOfOrder=Enabled (0), appends Log2 history with the authenticated manager and Sync=0, and verifies Log24 before commit. It does not start a cycle, modify Enabled, erase the AutoOutOfOrder state or confirm device acknowledgement. Response: kid, outOfOrder=0, status=Enabled, timestampUtc, revision, sync.
GET /api/v1/units/out-of-service?pageSize=50
Authorization: Bearer SESSION_TOKEN
Accept-Language: en-GB
POST /api/v1/units/UNIT_KID_FROM_LIST/out-of-service/restore
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json
{"expectedRevision":"COPY_THE_64_HEX_REVISION_FROM_THE_ITEM"}
400: invalid KID/page/revision/cursor (restart expired paging). 401: sign in again. 403: check OutOfOrder1, Bank/Location/Unit Read, matching resource grants and Unit Write for restore. 404: no longer visible or eligible for restore. 409 out-of-order-conflict: reload before deciding again. 503 out-of-order-unavailable: storage unavailable; an error is never an empty list. After a timeout, lost response or 503 during POST, read back before deciding whether to retry; never replay automatically. Responses are no-store. Managers cannot switch tenant by supplying a different KID.
Open the single-file OutOfOrder1 example or save its HTML. It shares the existing examples' remembered manager bearer session, never stores the API key, follows every page, and confirms each restore. Serve the saved file at http://localhost:8080 or http://127.0.0.1:8080. These exact origins can call the two operations with bearer authentication; cookies are not enabled. Host has no resource endpoints; its example offers synthetic demo data. Downloadable clients are updated during beta preparation.
AutoOutOfOrder
Optional autoOutOfOrderOnly=true filters units by valid Log24 AutoOutOfOrder JSON with a positive integer Id, independently of the OutOfOrder setting. The optional response field autoOutOfOrder contains that JSON when filtering, otherwise null. Follow nextCursor with the same filter to read all matches; each page rechecks Units1, Bank/Location/Unit Read, scope and RetentionDays. 400: invalid or changed cursor; 401/403: authentication/access; 503: storage unavailable. Unreleased; client packages follow at beta preparation.
GET /api/v1/units?autoOutOfOrderOnly=true&sort=kid&fields=bankName,locationName
Authorization: Bearer YOUR_TOKEN
GetPublicMachineErrors
No login or bearer token is required. The site selects the tenant. Returns items (kid, name, bankName, locationName, errorId as a digit string), nextCursor and refreshAfterSeconds=60. Only positive AutoOutOfOrder IDs whose Log24 MS2000 event time is within the last 10 days (inclusive) are included. Unknown and future timestamps are excluded. Deleted banks/locations/units and disabled locations are excluded; disabled units remain included. No raw error payload is public. pageSize=1–100 (default 50); follow nextCursor unchanged with the same pageSize. The portal loads every page automatically and fits all icons into its card. Cursors expire after 15 minutes and cannot cross tenants. 400 invalid page/cursor; 503 unavailable (Retry-After: 60), never an empty success. Unreleased.
GET /api/v1/public/widgets/machine-errors?pageSize=100
Wallboard map presentation
GetPublicWidgetPresentation (GET /api/v1/public/widgets) also returns mapProvider (google or maptiler) and nullable mapTilerBrowserKey. The trusted API tenant selects the provider. LocationMap (36) and purchase-map widget (7) can use MapLibre with MapTiler vector tiles: water remains transparent and purchase coins land at their geographic coordinates. This changes rendering only; location authorization and purchase data endpoints are unchanged. Heatmap (8) and ordinary portal maps retain Google.
For a wallboard purchase-map embed, pass wallboardMap: true with showCoins: true and showHeatmap: false. Ordinary embeds default to the existing Google renderer. An enabled MapTiler provider without a usable key rejects ready; it does not silently switch providers. MapTiler browser keys must permit the embedding page origin. Keep the visible MapTiler logo and MapTiler/OpenStreetMap attribution. A restrictive CSP must permit the bundled MapLibre script/style, blob workers, and HTTPS map/font requests to api.maptiler.com.
Purchase map widget
Mount the compact live purchase map directly, inside its own Shadow DOM. No iframe, portal shell, login or bearer token is required. The API site selects the tenant. Data refreshes every 10 seconds; failures back off for 30 seconds. Call destroy() when removing the widget. Supply googleMapsBrowserKey from the embedding website's public browser-key configuration; never use a server geocoding key. The option takes precedence over the nullable googleMapsBrowserKey from GetPublicWidgetPresentation (available only when the API already has GoogleMaps:ApiKey configured). The API does not need that setting when the embedding site supplies its own key. Without either source, ready rejects. Google HTTP-referrer restrictions must allow the embedding site; the widget does not change them. For sites with Content Security Policy, also follow Google Maps CSP guidance.
After widget.ready, widget.getView() returns the current { startPosition: { latitude, longitude }, zoom }, or null when unavailable or destroyed. It reflects manual map movements. Unreleased.
Set startPosition: { latitude: 56.2, longitude: 10.5 } to choose the initial map centre. Latitude must be from -90 to 90 and longitude from -180 to 180. Combine with zoom: 6. With startPosition, automatic data fitting is skipped; live purchase following and manual navigation remain available. Omit it to keep automatic fitting. Available in source; unreleased.
Map layers: showCoins defaults to true; showHeatmap defaults to false. For a heatmap-only card, set showCoins: false, showHeatmap: true. Available in source; unreleased.
Set zoom: 7 to use a fixed zoom level after centering on the data. Values from 0 to 22 are supported. Omit zoom to fit all locations automatically. Unreleased.
Latest photo widget
Unreleased. GetPublicRecentCameraPhotos: GET /api/v1/public/camera/photos returns up to ten photos (including Live Photo stills), newest capture first, across the configured tenant. No login or tenant input. Each item contains thumbnailUrl and workspacePath. Fetch thumbnailUrl unchanged (GetPublicCameraThumbnail); tickets expire after ten minutes and only allow JPEG thumbnails. Original media, owner details and sensor metadata remain private. Opening workspacePath requires an active manager with Camera1, resource Read, scope and retention visibility. The overview shows each image for three seconds (component parameter DisplaySeconds, 1–60), with a 500 ms fade, pause control and reduced-motion support. Refresh the list every minute; do not persist tickets. Empty array means no photos. 400: invalid/expired/cross-tenant ticket; 404: missing thumbnail; 503: unavailable or incomplete storage snapshot. Retry after one minute. Both regional indexes must be available; scans are bounded to 10,000 index entries and 200 candidate manifests. Videos are excluded; no database writes or direct storage URLs.
GET /api/v1/public/camera/photos
Manager API keys (unreleased)
In Portal, open My settings and choose Generate key. GetMyManagerApiKey — GET /api/v1/session/me/api-key returns hasApiKey and revision. GenerateMyManagerApiKey — POST /api/v1/session/me/api-key accepts {"revision":"REVISION_FROM_GET"} and returns the one-time apiKey plus details with the new status/revision. An active tenant-bound manager can generate only their own key, without administrative permissions. Copy the plaintext immediately; it cannot be recovered. Never log this response.
Both Portal LoginManager and Equipment LoginService accept {"kid":"CANONICAL_MANAGER_KID","apiKey":"YOUR_KEY"} at POST /api/v1/session/login. Email/password remains supported; do not mix pairs. Choose the correct tenant host; tokens are isolated between APIs and environments. KID login does no duplicate-account cleanup. The token retains the manager's existing Tab/KID/operation permissions and ten-day lifetime. It never grants service synchronization rights. Renew after activity; replacement of the key revokes key sessions within 60 seconds, including renewed sessions.
Manager and service generation store only the password-compatible hash in eSetting.ApiKeyHash, preserving Password. For services, ApiKeyHash is authoritative when present; an explicitly empty value disables the key. Existing service keys stored only in Password remain readable until replaced. Never copy manager passwords into ApiKeyHash. Handle 400 for invalid/mixed input, 401 for invalid key or inactive manager, 409 for concurrent generation (reread the status), and 503 for unavailable or uncertain storage. Never retry generation automatically.
API-key login username
LoginManager · POST /api/v1/session/login — Unreleased. For manager API-key login, send the username shown in My settings in the kid field: Kid.ToUserId format, tenant.0-userId (for example 166.0-1000002303). Send apiKey with the original key. The canonical manager KID is also accepted. The tenant must match the configured API host; only bank-zero managers are accepted. Resource IDs and response KIDs remain canonical. Do not mix kid/apiKey with email/password.
Nearest accessible locations
GetNearestLocations — GET /api/v1/locations/nearest?latitude=55.6761&longitude=12.5683 returns up to ten enabled locations as an array of {kid,name,bankName,iconKid,distanceMeters}, ordered by straight-line distance in metres. Supply both finite coordinates in decimal degrees (latitude −90…90, longitude −180…180). No search filter or radius applies; locations without valid nonzero coordinates are omitted. Requires an active manager, Locations1, Bank Read, Location Read and matching KID scope; retention visibility is preserved. No extra permissions are granted by a position. Errors: 400 invalid-position, 401 invalid session, 403 missing-locations-access, 503 locations-unavailable. An empty array means no eligible locations. Responses are no-store. Positions are used only for this lookup; do not log query strings or persist them. The portal retrieves the browser position automatically when the card appears. The browser may request location permission; refusal or unavailable positioning produces a localized message.
Reservation history
GetLocationReservationHistory — GET /api/v1/locations/{locationKid}/reservation-history Each item also includes canonical userKid (null for an unknown resident). For display only, fall back to userKid when userNumber is empty; userName remains empty when unavailable.
Load history for the visible calendar range only. Requires Bookings1, Location Read, Unit Read, matching resource scope and retention visibility. Returns bank Log5 revisions for visible units with userNumber and userName from bank Log7 (empty strings when missing); User Read is required. From is a local date from 2001; days is 1–31. Each item contains unitKid, startMinute (local minutes since 2000-01-01), durationMinutes (positive absolute duration), revision (UTC milliseconds since 2000-01-01) and cancelled. Superseded and cancelled events remain in history; weekly/AUT/isy events are omitted. History does not describe current occupancy. On 400 correct the range/KID, on 401 sign in again, on 403 check permissions, on 404 refresh the location, and on 503 retry later and show history as unavailable. The 5000-event limit fails with 503 instead of truncating. Unreleased.
GET /api/v1/locations/LOCATION_KID/reservation-history?from=2026-10-20&days=7
Authorization: Bearer YOUR_MANAGER_TOKEN
The event matching a current active reservation by MS2000, LocationId, UnitId and UserId in the same trusted tenant and bank is omitted from history.
Resident lookup and eVaskeri example
Open the single-file example. It shares manager login/renewal with all manager examples. Search by complete email (SearchUsers), phone (SearchUserSms), activation code (SearchUserActivation), or resident KID (SearchUsers with kidOnly=true), across the site's authorized banks. KIDs can be canonical, readable or site-relative. No bank selection is needed. Requires Users2 (53), User Read and resource grants; Bank Read adds authorized parent-bank names.
Resident SearchResult items include a canonical bankKid. Join authorized Bank context by that KID, not array order. Missing bank context does not grant access or supply a bank name. At most 50 residents / 501 examined candidates; hasMore marks incomplete results with no cursor. Existing retention checks and 60-second search caches apply. Activation search shares 5 attempts/10 minutes and 20/hour across code providers; honor 429 Retry-After without automatic retry. Search values and results are not stored by the example.
GET /api/v1/search/users?q=anna%40example.test
GET /api/v1/search/user-sms?q=4512345678
GET /api/v1/search/user-activation?q={activationCode}
GET /api/v1/search/users?q={userKid}&kidOnly=true
Authorization: Bearer {managerToken}
CreateUserEvaskeriSession
POST /api/v1/users/{userKid}/evaskeri-session, no request body required. Returns { kid, url, expiresAtUtc }. Requires an active manager, Users2, User Read/Create and tenant-wide or whole-bank scope. Location-only scope is insufficient because the link opens the resident's entire account. The API refreshes the manager snapshot and reads authoritative resident Log7 state; only active residents with an Access location qualify. Canonical resident KIDs must belong to the trusted site. Only Nortec is supported; other tenants never use its destination.
const response = await fetch(`${api}/api/v1/users/${encodeURIComponent(userKid)}/evaskeri-session`, {
method: "POST", headers: { Authorization: `Bearer ${managerToken}` }, cache: "no-store"
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { url, expiresAtUtc } = await response.json();
// Open url immediately in the user-requested window with no opener or referrer.
// See the example for popup blocking, response validation and cancellation.
The URL is a sensitive bearer credential in the existing DatPro2/eVaskeri format. Do not log, cache, persist, share or prefetch it. Legacy eVaskeri accepts it for ten days, may reuse it, and does not revoke it on Portal logout. expiresAtUtc is the admission deadline; the resulting session follows eVaskeri's own rules. This opens the full resident application and permits resident actions. The endpoint itself changes no resident settings, bookings or messages.
Errors: 400 invalid/foreign KID; 401 expired/revoked manager session; 403 permissions/scope; 404 missing/deleted resident; 409 no active location; 501 unsupported tenant; 503 unavailable storage. Nothing retries automatically. Available in the alfa source preview; not yet released to beta/production.
Unit WashDoc lists and their separate count accept optional search: an exact numeric Doc ID or canonical document KID belonging to the selected unit. The inclusive date cutoff still applies. Invalid or other-unit identities return HTTP 400 invalid-document-search. Clear search to restore unfiltered history. Routed API responses may include X-Portal-Operation, the stable Swagger operation name, for contextual documentation; it contains no request values.
Activity and application-load widgets
Electrolux (333), Hub (555) and Finelec (888) also support PortalApiLoad (50) and DatabaseLoadHistory (37). Widget 50 reads only that tenant’s dedicated beta Portal apps in FRA/AMS: Web and API share a container, so these are combined Portal/API measurements, not separate API process metrics. The application response adds optional scope=portal-beta, series region (FRA/AMS), and unavailableRegions; partial regional histories remain visible without summing percentages. Widget 37 reads that tenant’s verified current MySQL cluster, shared by its beta/production data. Team keeps its existing production mappings. Missing configuration never falls back to another tenant. All require Wallboard1, Hosting1, Managers Read and a whole-tenant grant, rechecked uncached before and after reads; protected widgets remain excluded from anonymous publication.
ActiveManagers (48) counts distinct enabled administrators across the trusted tenant whose current bank-zero Log7 Alive timestamp falls within the preceding 15 minutes. Successful password login and explicit interactive session renewal record activity through the shared transactional writer, at most once per minute. Screen polling and API-key renewal never record user activity. Only count, measuredAtUtc, refreshAfterSeconds (60) and activeWithinMinutes (15) are returned; no identities.
On Team, PortalWebLoad (49), PortalApiLoad (50) and EquipmentApiLoad (51) show the previous 24 hours of production CPU and memory percentages. Both axes start at zero and end at 100%; smoothing is presentation-only and tooltips retain measured values. Each component/instance stays a separate series; values are never summed. The fixed DigitalOcean app mapping and provider credentials remain server-side. The response contains fromUtc, toUtc, fetchedAtUtc, refreshAfterSeconds, cpuSeries and memorySeries; each series contains timestampUtc/value points only. A failed metric remains unknown while the other remains available.
All four types accept only an empty or theme-only KID. They are protected and cannot be published on the anonymous Portal wallboard. Wallboard1, Managers Read and an explicit whole-tenant grant are required; the load graphs additionally require Hosting1 and the tenant availability described above. Both manager credentials/permissions and exact saved display type/device approval are checked before and after reads. Preview operations reject screens. Sixty-second success/failure caches and bounded reads apply; unavailable data returns 503 rather than zero. Browser refresh pauses while hidden or offscreen.
GetMyWallboardActiveManagers — GET /api/v1/session/me/wallboards/active-managers
GetWallboardDisplayActiveManagers — GET /api/v1/session/me/wallboards/display/{displayId}/active-managers?portrait=false
GetMyWallboardApplicationLoadHistory — GET /api/v1/session/me/wallboards/application-load-history/{widgetType}
GetWallboardDisplayApplicationLoadHistory — GET /api/v1/session/me/wallboards/display/{displayId}/application-load-history/{widgetType}?portrait=false