REST API Reference

Complete REST API reference for Certexi including authentication, WHMS endpoints, workflow operations, IoT integrations, and governance routes.

Last updated: 2025-02-18

REST API Reference

Certexi exposes a comprehensive REST API through Next.js API routes. All endpoints return JSON and follow consistent error handling patterns.

ℹ️

OpenAPI spec

The canonical machine-readable reference is GET /api/openapi. Use it for code generation, Swagger UI, or Postman. To regenerate the full list of API routes from the codebase, run npm run docs:generate-api-list.

Authentication

All API requests (except /api/health and /api/ping) require authentication via headers:

Authorization: Bearer <token> | Basic <credentials>
X-NextCloud-Instance: <nextcloud_url>
X-NextCloud-Username: <username>

The API supports both OAuth Bearer tokens and Nextcloud App Password authentication with automatic fallback.

⚠️

Rate Limiting

API endpoints are rate-limited per user/IP. Default limits are 100 requests per minute. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Health & Monitoring

GET/api/health

System health check (no auth required)

Returns the health status of all system components.

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:00:00Z",
  "uptime": 86400,
  "version": "2.0.0",
  "checks": {
    "database": { "status": "healthy", "responseTime": 5 },
    "redis": { "status": "healthy", "responseTime": 2 }
  }
}
GET/api/metrics

Prometheus metrics (admin only)

Returns application metrics in Prometheus exposition format. Requires metrics:read permission.

Warehouse Management (WHMS)

Warehouses

GET/api/whms/warehouses

List all warehouses

Returns all warehouses accessible to the authenticated user.

POST/api/whms/warehouses

Create a warehouse

{
  "name": "Main Warehouse",
  "location": { "lat": 19.43, "lng": -99.13 },
  "timezone": "America/Mexico_City"
}
GET/api/whms/warehouses/:id

Get warehouse details

Returns warehouse metadata, zone summary, and utilization statistics.

Zones

GET/api/whms/zones

List all zones

Returns zones with slot counts and occupancy data.

POST/api/whms/zones

Create a zone

{
  "name": "Zone A",
  "zone_type": "storage",
  "color": "#3b82f6",
  "warehouseId": 1
}
GET/api/whms/zones/:id/slots

List slots in a zone

Returns all slots within a zone with current occupancy status.

Slots

GET/api/whms/slots

List all slots

Returns all slots with computed occupancy from the event ledger.

GET/api/whms/slots/:id

Get slot with occupancy status

Returns slot metadata and computed current status: isOccupied, assetBarcode, isVerified.

POST/api/whms/slots

Create a slot

{
  "slot_id": "A-01-01",
  "zone": "A",
  "floor_plan_polygon": [
    { "x": 10, "y": 20 },
    { "x": 50, "y": 20 },
    { "x": 50, "y": 60 },
    { "x": 10, "y": 60 }
  ]
}

Transport Units

GET/api/whms/transport-units

List transport units

Returns all transport units with current stage and status.

GET/api/whms/transport-units/:id

Get transport unit details

Returns full transport unit record including workflow history and evidence.

Events

GET/api/whms/events

Query event history

Supports filtering by slot_id, asset_barcode, event_type, and pagination via limit/offset.

POST/api/whms/events

Create a placement event

{
  "event_type": "PLACED",
  "slot_id": 5,
  "asset_barcode": "PLT-2024-00001",
  "operator": "op-123",
  "photo_url": "https://cloud.example.com/evidence/photo.jpg",
  "scale_weight_kg": 1250
}

Assets

GET/api/whms/assets

List assets

Returns all registered assets with type and metadata.

GET/api/whms/assets/:barcode/location

Get asset location

Returns the current location (slot) of an asset derived from the event ledger.

Dashboard

GET/api/whms/dashboard/utilization

Zone utilization statistics

{
  "totalSlots": 200,
  "occupiedSlots": 142,
  "utilizationPercent": 71,
  "pendingVerifications": 8,
  "byZone": [
    { "zone": "A", "occupied": 45, "total": 60 },
    { "zone": "B", "occupied": 38, "total": 50 }
  ]
}

IoT & Surveillance

GET/api/iot/cctv

List cameras (filtered by ownership)

Returns cameras accessible to the authenticated user. RTSP URLs and credentials are never exposed.

POST/api/iot/detection/motion-stream

Start/stop motion detection

Control server-side FFmpeg motion detection per camera. See Motion Detection.

GET/api/iot/detection-events

Query detection events

Returns motion detection events with clip URLs and metadata.

Governance

GET/api/governance/audit

Query audit log

Returns audit trail entries with filtering by entity, operator, and time range.

POST/api/governance/incidents

Create an incident report

Log a compliance incident with severity, category, and evidence references.

Error Handling

All endpoints return standardized error responses:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "details": "Additional context"
  }
}

Common HTTP status codes: 400 (validation), 401 (unauthorized), 403 (forbidden), 404 (not found), 429 (rate limited), 500 (server error).

Related

REST API Reference | Certexi Docs