Assets API
POST/api/v1/assets/{id}/maintenance/record
Product availabilityAlgaPSA

Record asset maintenance

Inserts an asset_maintenance_history row for the path asset ID in the authenticated tenant. The request body requires maintenance_type, performed_by, and performed_at; schedule_id, duration, cost, notes, parts, and structured maintenance_data are optional. If schedule_id is supplied and a matching tenant schedule exists, the service updates that schedule last_maintenance and next_maintenance. It does not verify asset existence or performed_by before insert, does not set created_by, and publishes no event.

RBAC · asset

Path parameters

idstring <uuid>Required
Asset UUID from assets.asset_id.

Request body

Content type: application/json · schema AssetRecordMaintenanceRequest

schedule_idstring <uuid>
Optional maintenance schedule UUID. If present and found for the tenant, the schedule last_maintenance and next_maintenance are updated.
maintenance_typestringRequired
Required type of maintenance performed.
Enum: preventivecorrectiveinspectioncalibrationreplacement
performed_bystring <uuid>Required
Required UUID of the user who performed maintenance. The service does not validate this user before insert.
performed_atstring <date-time>Required
Required timestamp when maintenance was performed.
duration_hoursnumber
Optional duration in hours.
≥ 0
costnumber
Optional cost.
≥ 0
notesstring
Optional notes.
parts_usedarray of string
Optional list of parts used.
itemsstring
maintenance_dataobject
Optional structured maintenance data.

Response body

Success response 201 · schema AssetRecordMaintenanceResponse

successbooleanRequired
Enum: true
dataobjectRequired
dataobjectRequired
history_idstring <uuid>Required
Primary key from asset_maintenance_history.history_id.
asset_idstring <uuid>Required
Asset UUID from asset_maintenance_history.asset_id.
schedule_idstring <uuid>Nullable
Optional related maintenance schedule UUID.
maintenance_typeanyOfRequired
Maintenance type recorded for the history row.
anyOf (option 1)string
Enum: preventivecorrectiveinspectioncalibrationreplacement
anyOf (option 2)string
performed_bystring <uuid>Required
User UUID supplied in the maintenance record.
performed_atstring <date-time>Required
Timestamp when maintenance was performed.
duration_hoursnumberNullable
Maintenance duration in hours, when recorded.
costnumberNullable
Maintenance cost, when recorded.
notesstringNullable
Free-text notes.
parts_usedarray of stringNullable
Parts used, when recorded.
itemsstring
maintenance_dataobjectNullable
Arbitrary structured maintenance data.
descriptionstringNullable
Description column when present in the maintenance history table.
created_atstring <date-time>Required
History creation timestamp.
tenantstring <uuid>Required
Tenant UUID scoped from the request context.
performed_by_user_namestringNullable
Concatenated user name from the joined users table.
metaobjectRequired
timestampstring <date-time>Required
Response timestamp generated by createApiResponse/createErrorResponse.
versionstringRequired
API response version string.

Response codes

201
Maintenance record created successfully.
400
Request body validation failed or the database rejected an invalid reference.
401
x-api-key is missing at middleware.
403
Authenticated request context lacks permission to update asset maintenance records when auth wiring is present.
409
Database unique constraint conflict if one is enforced.
500
Unexpected error.