Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.novala.ai/llms.txt

Use this file to discover all available pages before exploring further.

Inspections are field records created when a technician inspects a piece of equipment at a site using a checklist template. Each inspection tracks its status through a review workflow and accumulates findings — discrete observations with severity ratings.
The inspections API requires the calso module to be enabled for your tenant. Requests made without the module active will return 403 Forbidden.

​
Inspection statuses

An inspection moves through the following lifecycle:
StatusMeaning
draftCreated, not yet submitted by the technician.
submittedSubmitted by the technician for review.
in_reviewUnder review by a coordinator or manager.
approvedInspection approved.
deliveredReport delivered to the customer.
rejectedReturned to the technician for corrections.

​
Finding severities

SeverityMeaning
imminentRequires immediate action; equipment should be taken out of service.
seriousSignificant deficiency requiring prompt repair.
minorLow-risk observation; should be addressed in routine maintenance.

​
List inspections

GET /api/inspections Returns a paginated list of inspections for the authenticated tenant.

​
Query parameters

​
status
string
Filter by inspection status. One of: draft, submitted, in_review, approved, delivered, rejected.
​
technicianId
string
Filter by technician UUID. Returns inspections where the user is the lead technician or a team member.
​
companyId
string
Filter by company (customer) UUID.
​
search
string
Full-text search across company name, equipment type name, technician name, and serial number.
​
page
integer
default:"1"
1-based page index.
​
limit
integer
default:"25"
Results per page. Maximum 100.

​
Response

{
  "data": [
    {
      "inspection": {
        "id": "e1b234cd-0001-4aaa-bbbb-ccccddddeeee",
        "status": "submitted",
        "inspectionDate": "2024-07-15",
        "overallResult": "conditional",
        "notes": "Customer was on-site during inspection.",
        "createdAt": "2024-07-15T08:00:00Z"
      },
      "equipment": {
        "id": "eq-uuid-001",
        "manufacturer": "Genie",
        "model": "S-65",
        "serialNumber": "GS65-001234"
      },
      "equipmentType": {
        "id": "type-uuid-001",
        "name": "Boom Lift",
        "category": "aerial"
      },
      "site": {
        "id": "site-uuid-001",
        "name": "Main Warehouse",
        "address": "123 Industrial Blvd",
        "city": "Austin",
        "state": "TX"
      },
      "customer": {
        "id": "cust-uuid-001",
        "name": "Acme Corp"
      },
      "technician": {
        "id": "user-uuid-001",
        "name": "Jordan Smith"
      },
      "findingCount": 3
    }
  ],
  "total": 47,
  "page": 1,
  "pageSize": 25
}

curl -X GET "https://app.novala.ai/api/inspections?status=submitted" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get an inspection

GET /api/inspections/{id} Retrieves a full inspection record including equipment details, checklist template, findings with photos, and the technician team.

​
Path parameters

​
id
string
required
UUID of the inspection.

​
Response fields

​
inspection
object
​
equipment
object
Equipment with id, manufacturer, model, serialNumber, ratedCapacity, status, nameplatePhotoUrl, locationLabel.
​
equipmentType
object
Equipment type with id, name, category, oshaStandard.
​
site
object
Site with id, name, address, city, state.
​
customer
object
Company with id and name.
​
technician
object
Lead technician with id, name, email.
​
template
object
Checklist template with id, name, and sections.
​
findings
array
​
teamMembers
array
Array of team members with id, technicianId, role (lead or member), and name.
curl -X GET https://app.novala.ai/api/inspections/e1b234cd-0001-4aaa-bbbb-ccccddddeeee \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create an inspection

POST /api/inspections Creates a new inspection in draft status. The inspection is assigned to the authenticated user unless a technicianId (or technicianIds) is specified, which requires the Admin or Coordinator role.

​
Request body

​
equipmentId
string
required
UUID of the equipment to inspect.
​
siteId
string
required
UUID of the site where the inspection takes place.
​
checklistTemplateId
string
required
UUID of the checklist template to use. Must belong to your tenant.
​
inspectionDate
string
required
Date of inspection in YYYY-MM-DD format.
​
notes
string
Pre-inspection notes.
​
technicianId
string
UUID of the lead technician. Only honored when the caller has the system_admin or field_coordinator role.
​
technicianIds
array
Array of technician UUIDs. The first element is the lead; subsequent elements are team members. Takes precedence over technicianId.

​
Response

Returns 201 Created with the new inspection object (without nested relations). Initial status is always draft. 
curl -X POST https://app.novala.ai/api/inspections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "equipmentId": "eq-uuid-001",
    "siteId": "site-uuid-001",
    "checklistTemplateId": "tmpl-uuid-001",
    "inspectionDate": "2024-08-20",
    "technicianIds": ["user-uuid-001", "user-uuid-002"]
  }'