API Endpoints (Overview)

This page lists available endpoint groups, routing rules, auth model, and practical request examples.

Authentication

• API access uses API keys generated in Configuration → API Keys (UI).
• Tokens are shown once; store securely.
• Header format:
  • Authorization: ApiKey <token> for API key calls
• API keys sent with Bearer are rejected.

Tenant routing (important)

The backend resolves the tenant/workspace from the request Host header:

• the tenant is inferred from the subdomain (the first .-separated segment)

Recommended production pattern:

• https://<tenant-subdomain>.invymate.com/api/v1/...

Local/test hosts depend on your deployment setup, but tenant is always host/subdomain-derived.

Common patterns

• Pagination/filtering/sorting vary by endpoint; see per-endpoint sections below.
• Standard error responses include message and optional details.
• Webhook management routes are JWT-only even when API Access is enabled.

Contract docs

Use these docs together:

• API Access: key creation and auth setup
• API Endpoints (Overview): endpoint groups, auth model, and query patterns (this page)
• Webhooks: delivery model and webhook signatures

Endpoints available via API key

All endpoints below are under the /api/v1 prefix and accept API key auth unless noted.

Categories

Base: /categories

• GET /categories
• GET /categories/default
• POST /categories
• PATCH /categories/:categoryId
• DELETE /categories/:categoryId
• POST /categories/:categoryId/restore

Locations

Base: /locations

• GET /locations
• GET /locations/default
• POST /locations
• PATCH /locations/:locationId
• DELETE /locations/:locationId
• POST /locations/:locationId/restore

Assets (Inventory items)

Base: /inventory-items

• GET /inventory-items
• POST /inventory-items
• GET /inventory-items/:inventoryItemId
• PATCH /inventory-items/:inventoryItemId
• DELETE /inventory-items/:inventoryItemId
• POST /inventory-items/:inventoryItemId/restore
• GET /inventory-items/:inventoryItemId/assignment-history
• GET /inventory-items/:inventoryItemId/audit
• GET /inventory-items/:inventoryItemId/allowed-status-transitions
• GET /inventory-items/:inventoryItemId/status-events
• GET /inventory-items/:inventoryItemId/timeline
• GET /inventory-items/:inventoryItemId/health
• POST /inventory-items/health/batch
• POST /inventory-items/:inventoryItemId/status

GET /inventory-items list view now includes per-item health:

• health.score (0..100)
• health.badge (HEALTHY | ATTENTION | AT_RISK)
• health.reasons[]

GET /inventory-items supports health list controls:

• healthBadge (HEALTHY | ATTENTION | AT_RISK)
• healthSort (risk_first | healthy_first) — used by the Assets table Health column sort

GET /inventory-items/:inventoryItemId/timeline query params:

• limit (default 50, max 100)
• cursor (opaque pagination cursor from previous response)
• types (optional comma-separated list):
  • CREATED
  • ASSIGNED
  • UNASSIGNED
  • MOVED
  • MAINTENANCE_COMPLETED
  • VERIFIED
  • STATUS_CHANGED
  • RETIRED

GET /inventory-items/:inventoryItemId/health returns:

• score (0..100)
• badge (HEALTHY | ATTENTION | AT_RISK)
• reasons[] with reason codes and optional links

POST /inventory-items/health/batch accepts:

• ids[] (asset ids, 1..200)

Returns:

• items[] with id, score, badge, reasons

POST /inventory-items/:inventoryItemId/status accepts:

• toStatus
• reason (required for retired)
• meta (optional context, e.g. reservation details)

Example:

{
  "toStatus": "reserved",
  "reason": "Reserved for onboarding",
  "meta": {
    "reservedUntil": "2026-03-01T09:00:00.000Z",
    "reservationReason": "New hire starts Monday"
  }
}

For maintenance, optional meta keys include:

• no special keys are required; completion is tracked via POST /maintenance/logs

Ad-hoc maintenance completion example:

{
  "itemId": "<inventory-item-id>",
  "type": "repair",
  "completedDate": "2026-02-22T10:00:00.000Z",
  "notes": "Fan replaced and thermal test passed"
}

People

Base: /people

• GET /people
• POST /people
• GET /people/:personId
• PATCH /people/:personId
• DELETE /people/:personId
• POST /people/:personId/restore
• GET /people/:personId/assignment-history

Custom fields

Base: /custom-fields

• GET /custom-fields
• POST /custom-fields
• PATCH /custom-fields/:customFieldId
• DELETE /custom-fields/:customFieldId
• POST /custom-fields/:customFieldId/restore

Maintenance

Base: /maintenance

Schedules:

• POST /maintenance/schedules
• GET /maintenance/schedules/due/all
• GET /maintenance/schedules/item/:itemId
• GET /maintenance/schedules/:id
• PATCH /maintenance/schedules/:id
• DELETE /maintenance/schedules/:id

GET /maintenance/schedules/due/all query params:

• lookaheadDays (1..60, default 7)
• Alias also accepted: reminderDays

Reminder classification:

• overdue: nextDueDate < now
• due today: nextDueDate is today
• upcoming: nextDueDate > now and within schedule reminderDays

Logs:

• POST /maintenance/logs
• GET /maintenance/logs/item/:itemId
• GET /maintenance/logs/schedule/:scheduleId
• GET /maintenance/logs/:id
• PATCH /maintenance/logs/:id
• DELETE /maintenance/logs/:id

Webhooks (management API)

Base: /webhooks

Auth:

• Requires JWT auth (Authorization: Bearer <jwt>)
• API key auth is not supported on webhook management routes
• Pro feature gate applies

Endpoints:

• GET /webhooks/endpoints
• POST /webhooks/endpoints
• PATCH /webhooks/endpoints/:id
• DELETE /webhooks/endpoints/:id
• POST /webhooks/endpoints/:id/verify
• GET /webhooks/health
• GET /webhooks/deliveries
• GET /webhooks/deliveries/:id
• POST /webhooks/deliveries/:id/replay
• POST /webhooks/events/:id/replay

GET /webhooks/deliveries query params:

• endpointId (optional)
• status (optional)
• eventType (optional)
• dateFrom (optional ISO date/time)
• dateTo (optional ISO date/time)
• limit (1..100, optional)

GET /webhooks/health query params:

• windowMinutes (5..1440, optional, default 60)

Trash (restore / permanent delete)

Base: /trash

• GET /trash
• POST /trash/restore
• POST /trash/permanent-delete