Docs
← Back to Docs
Last updated: 2026-04-11

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
  • POST /inventory-items/:inventoryItemId/checkout
  • POST /inventory-items/:inventoryItemId/checkin
  • POST /inventory-items/quick-add/events (JWT auth)

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

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

  • personId (required)
  • dueBackAt (optional ISO date/time)

POST /inventory-items/:inventoryItemId/checkin:

  • clears assignee and records check-in timestamps/history
  • keeps location unchanged

POST /inventory-items/quick-add/events accepts:

  • event (quick_add_opened | asset_created_quick | asset_assigned | advanced_opened)
  • flowId
  • optional itemId
  • optional meta

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

Inventory sessions (audits)

Base: /sessions

  • GET /sessions
  • GET /sessions/active
  • GET /sessions/:sessionId
  • POST /sessions
  • PATCH /sessions/:sessionId
  • DELETE /sessions/:sessionId
  • GET /sessions/:id/items
  • GET /sessions/:id/items/:itemId
  • POST /sessions/:id/items/:itemId/include
  • POST /sessions/:id/items/:itemId/exclude
  • GET /sessions/:id/missing
  • GET /sessions/:id/report
  • POST /sessions/:id/scan
  • POST /sessions/:id/unscan
  • GET /sessions/:id/mobile

POST /sessions/:id/scan is idempotent and returns:

  • accepted
  • already_scanned
  • not_in_session
  • wrong_location (for location-scoped sessions unless allowMarkAnyway is true)

Mobile/client scan payload accepts either:

  • itemId, or
  • code (QR value such as an asset URL)

Optional scan flags:

  • allowMarkAnyway (for location mismatch override)
  • allowRescan (explicitly re-write an already scanned item event)

GET /sessions/:id/mobile returns a fast mobile payload:

  • session identity/status/location
  • progress counts (scanned, total)
  • recent scans list for scan-loop UI

Stats / analytics

Base: /stats/analytics

  • GET /stats/analytics/overview
  • GET /stats/analytics/sessions
  • GET /stats/analytics/lifecycle
  • GET /stats/analytics/maintenance
  • GET /stats/analytics/depreciation
  • GET /stats/analytics/replacement-loss
  • GET /stats/analytics/reports

GET /stats/analytics/replacement-loss provides:

  • age buckets + age-by-category + oldest assets
  • warranty expiry counts/lists (30/60/90 days)
  • long-assigned assets and threshold counts
  • missing-rate trends (location/category) + repeatedly unscanned assets

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

The admin API includes a TT10 report endpoint for quick-add onboarding diagnostics:

  • GET /admin/tenants/:tenantId/tt10-report?from=<ISO>&to=<ISO>

Response includes per-user entries with:

  • first created time
  • tenth assigned time
  • computed tt10Minutes
  • meetsTarget (tt10Minutes < 10)
← API AccessWebhooks →