Assets - API Reference

Audience: Frontend engineers, mobile/panel engineers, backend engineers, QA, and the accounting integration's developers (for the read-only vocabulary the accounting API mirrors). Scope: Admin (/api/assets/**, /api/asset-catalog/**, /api/asset-settings/**, /api/asset-reports/**, /api/asset-sync/**) and mobile portal (/api/mobile/staff/assets) routes owned by the asset management module. The accounting-facing sync payload shape is documented alongside the integration module.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. Admin Routes — Catalog

5. Admin Routes — Register

6. Admin Routes — Sync, Reports, Settings

AssetSyncController carries @RequiresAccountingIntegration() at the class level, so all three /api/asset-sync/** routes above — reads included — answer 404 ACCOUNTING_INTEGRATION_DISABLED while the school's accounting-integration switch is off, checked after JwtAuthGuard/RoleGuard. See the integration module's docs for the switch itself. | GET | /api/asset-reports/dashboard | Assets_READ | Counts by status/category/type | | GET | /api/asset-reports/export | AssetExports_READ | CSV export of the register | | GET | /api/asset-settings | AssetSettings_READ | Read global asset settings | | PATCH | /api/asset-settings | AssetSettings_UPDATE | Update global asset settings | | GET | /api/asset-settings/notifications | AssetSettings_READ | Read the notification matrix override | | PUT | /api/asset-settings/notifications/:eventKey | AssetSettings_UPDATE | Override one event's audiences/channels |

7. Mobile/Portal Route

8. Error Codes

9. Integration Notes

The accounting application never talks to /api/assets/** directly. It reads the asset change feed (asset.* events, gated by the assets:read scope) and writes only through the inbound sync path, gated by assets:write. See the integration module's docs for the client-facing request/response shapes and INTEGRATION_EVENT_SCOPE.

10. DTOs — Catalog

CreateAssetTypeDto: code (required, ^[A-Z][A-Z0-9_]{1,29}$) · name (required, ≤80) · description (optional nullable, ≤500) · sortOrder (optional int ≥0, default 0). UpdateAssetTypeDto: name/description/sortOrder optional, plus status (optional, AssetCatalogStatus) and required version. AssetTypeDto (response) adds publicId, categoryCount, assetCount, createdAt/updatedAt.

CreateAssetCategoryDto: typeId (required uuid) · code (required, same pattern) · name (required, ≤80) · description (optional nullable, ≤500) · accountingCode (optional nullable, ≤64 — the chart-of-accounts mapping). UpdateAssetCategoryDto: typeId is immutable — every other field optional, plus status and version. AssetCategoryDto adds type ({publicId, code, name}), assetCount.

CreateAssetLocationDto: name (required, ≤120) · locationType (required, AssetLocationType) · description (optional nullable, ≤500). UpdateAssetLocationDto: all fields optional plus isActive (bool) and version. AssetLocationDto adds assetCount.

AssetVersionBodyDto/AssetVersionQueryDto (shared, asset-common.dto.ts): a single version field (int ≥1) — the body form on every mutating POST/PATCH, the query form (?version=) on the three catalog DELETE routes, since a DELETE has no body. AssetSubResourceQueryDto (events/maintenance-history lists): pagination (default true), page/size (default 1/20, size capped 100).

Lookup DTOs (asset-catalog/rooms, /staff, /departments): AssetRoomLookupDto (publicId, roomNumber, name nullable, building, floor, classes — an array of AssetRoomClassDto: id the class's public_id, label its display name), AssetStaffLookupDto/AssetDepartmentLookupDto (publicId, name, and for staff employeeCode) — all read-only pickers behind AssetCatalog_READ, each accepting the shared QueryDto search/pagination params only. AssetRoomLookupQueryDto adds building (optional, ≤128 — exact match, case-insensitive); the inherited search matches roomNumber, name or building, each case-insensitively. classes lists the ACTIVE classes of the CURRENT academic session (academic_sessions.is_current) whose home room is this one, ordered by grade then section, each labelled by the class's own name when set or "<grade name> — <section name> — <Morning|Day>" otherwise, the same words the Classes screen uses; a room with no such class, or when no session is current, gets []. GET /api/asset-catalog/rooms/buildings returns ResponseDto<string[]> — no request DTO, no pagination envelope, just the distinct building names of active rooms.

Both the classes rule above and the building list come from RoomOccupancyService (academic-structure/rooms/room-occupancy.service.ts), owned by the academic-structure module and injected here because AssetCatalogModule imports AcademicStructureModule. The school's own Rooms API (GET /api/rooms, GET /api/rooms/buildings) calls the identical service — a room's classes and buildings read the same way regardless of which surface asks, and the school Rooms API additionally exposes assetCount per room (non-deleted assets whose status is not disposed), which this picker has no use for and does not return.

11. DTOs — Register

CreateAssetDto: name (required, ≤150) · typeId/categoryId (both required uuid) · description (optional nullable, ≤2000) · serialNumber (optional nullable, ≤120) · model/manufacturer (optional nullable, ≤120 each) · vendor (optional nullable, ≤150) · purchaseDate (optional nullable ISO date) · purchaseReference (optional nullable, ≤128) · purchaseCostPaisa (optional nullable int, 0-999,999,999,999) · warrantyExpiresOn (optional nullable ISO date) · warrantyNotes (optional nullable, ≤2000) · quantity (optional int, 1-100,000, default 1) · condition (optional, AssetCondition, default new) · notes (optional nullable, ≤2000). Registers as status: draft — there is no status field on this DTO; use activate afterward. UpdateAssetDto: every descriptive field above except typeId/categoryId/quantity-shape is patchable, plus required version; status, custody, place, accounting and disposal columns are never touched by this route — they move only through the dedicated action endpoints below.

ListAssetsQueryDto extends QueryDto with: status (optional array of AssetStatus, accepts a single value or a list), typeId/categoryId/custodianStaffId/custodianDepartmentId/roomId/locationId (all optional uuid filters), building (optional, ≤128 — assets whose room's building matches case-insensitively; an asset placed in a location, not a room, never matches), classId (optional uuid — assets placed in that class's home room; a class with no room, or an unknown class, matches nothing), condition (optional), sort (name/assetCode/purchaseDate/createdAt, default createdAt), warrantyExpiresWithinDays (optional int, 1-365 — matches assets whose warrantyExpiresOn falls between today, on the school calendar, and today + N days inclusive, and excludes drafts). The inherited search matches the asset name case-insensitively, with % and _ treated literally. The same DTO drives GET /api/asset-reports/export: every filter, including building and classId, the search and the warranty window apply there exactly as on the list, so an export of a filtered view carries the same assets. The export ignores sort and order and always orders rows by asset code, and it refuses with VALIDATION_FAILED when more than 5,000 rows match.

Action bodies, all requiring version except where noted:

Response DTOs: AssetSummaryDto (list/detail base) carries publicId, assetCode, name, type/category refs, status, condition, serialNumber, quantity, holder (AssetHolderDto: nullable staff/department refs), place (AssetPlaceDto: nullable room/location refs — the room ref, AssetRoomRefDto, carries publicId, label ("<building> · <roomNumber>[ (<name>)]", the same shape the school Rooms screen writes; the same label is used in the asset timeline, the My assets portal and the CSV Place column) and floor; floor is typed nullable but is always populated whenever room itself is present, since a room's floor column is required — place.room as a whole is null for an asset that is not room-placed), warrantyExpiresOn (nullable AssetDateDto), accountingStatus, updatedAt, version. AssetDetailDto extends it with description, model/manufacturer/vendor, purchaseDate/purchaseReference/purchaseCostPaisa, warrantyNotes, notes, assignedAt, accounting (AssetAccountingDto: status/reference/bookValuePaisa/updatedAt), disposal (nullable AssetDisposalDto), openMaintenance (nullable AssetMaintenanceDto), attachmentCount, createdAt, allowedActions. AssetEventDto (GET :id/events) mirrors the asset_events columns documented in the backend page. AssetAttachmentDto: publicId, fileName, contentType, sizeBytes, uploadedByName, createdAt — the upload route (AssetAttachmentUploadDto) documents only file (multipart binary; multer strips it from the body before validation runs).

12. DTOs — Sync, Reports, Settings

ListAssetSyncEventsQueryDto: state (optional, AssetInboundState), assetId (optional uuid). ResolveAssetSyncEventDto: action (required, accept/dismiss), method (optional, an AssetDisposalMethod, default written_off — used only when accepting a disposal-shaped conflict), note (required, 3-2000). AssetSyncEventDto (response): publicId, asset ({publicId, assetCode, name}), state, incoming/previous (raw JSON snapshots for the diff view), externalUpdatedAt, resolution (nullable), resolvedAt/resolvedByName/resolutionNote (nullable), receivedAt.

AssetDashboardDto (GET asset-reports/dashboard): total, byStatus/byCondition (free-form {value: count} records), byType (array of AssetTypeCountDto: typeId — the type's public_id, grouped so two types sharing a name are never merged — type, count; ordered by count desc then name asc), warrantyExpiringWithin30Days, openMaintenance, heldAccountingConflicts, recentEvents (array of AssetDashboardEventDto, which extends AssetEventDto with assetId — the triggering asset's public_id — assetCode, assetName; not filtered by the asset's own deletion state, since this is history). warrantyExpiringWithin30Days is the dashboard's fixed-window count for the same predicate ListAssetsQueryDto.warrantyExpiresWithinDays=30 applies to the register list.

UpdateAssetSettingsDto: accountingClientId (required, nullable uuid — null clears the designated client), version. AssetSettingsDto (response): accountingClient (nullable {publicId, name, status}), version, updatedAt. UpdateAssetNotificationSettingDto: isEnabled (required bool), audiences (required array, subset of AssetNotificationAudience: custodian/admin), channels (required array, subset of in_app/push/email/sms), version. AssetNotificationSettingDto (response) adds allowedAudiences — the matrix's ceiling for that event key.

13. DTOs — Self Route

AssetPortalItemDto (GET /api/mobile/staff/assets, no request DTO — the route takes no query beyond auth): id, assetCode, name, category, type, condition, assignedAt (nullable ISO timestamp), place (nullable {kind: "room" | "location", name}). Never exposes purchase cost, accounting fields, or disposal data — this is the custodian's own read, not the register.

14. Error Codes by Route Group

Every mutating route can also return the shared codes: VALIDATION_FAILED, PERMISSION_INSUFFICIENT, and the group's own _NOT_FOUND.