insp.ac API

Resource coverage

These four resources are designed to work as a connected workflow: user profiles hold current location context, check-ins track active presence at sites, logs/comments capture operational notes across entities, and sensor readings capture external telemetry inputs.

Resource	Purpose	Primary scopes
`Users`	Profile records and last-known location context for a user	users:read, users:write
`Checkins`	Lifecycle tracking for on-the-way, active, and closed presence	checkins:read, checkins:write
`Logs`	Append-only comments, notes, and status entries for entities	logs:read, logs:write
`SensorReadings`	Batch ingestion and retrieval of sensor telemetry	sensors:read, sensors:write

Endpoint matrix

Endpoint	Use case	Scope
`GET /v1/users`	List user profiles	users:read
`POST /v1/users`	Create user profile	users:write
`GET /v1/users/{id}`	Get user profile	users:read
`PATCH /v1/users/{id}`	Update user profile/location context	users:write
`GET /v1/checkins`	List check-ins	checkins:read
`POST /v1/checkins`	Create check-in	checkins:write
`GET /v1/checkins/{id}`	Get check-in	checkins:read
`PATCH /v1/checkins/{id}`	Update check-in lifecycle	checkins:write
`GET /v1/logs`	List logs/comments for an entity	logs:read
`POST /v1/logs`	Create log/comment entry	logs:write
`GET /v1/logs/{id}`	Get log entry	logs:read
`GET /v1/sensor-readings`	List sensor readings	sensors:read
`POST /v1/sensor-readings`	Ingest one or more sensor readings	sensors:write
`GET /v1/sensor-readings/{id}`	Get sensor reading	sensors:read

1) Create user profile and location context

Create one profile per external user identity, then update the last-location fields as check-ins or device updates arrive.

Create a user profile

curl -X POST https://api.insp.ac/v1/users \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: user-user_123-create" \
  -d '{
    "userId": "user_123",
    "lastLocationSiteId": "site_001",
    "lastLocationSource": "site_checkin_created",
    "lastLocationCapturedAt": "2026-02-18T14:10:00.000Z"
  }'

Update user location snapshot

curl -X PATCH https://api.insp.ac/v1/users/profile_123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: user-profile_123-loc-20260218T1420Z" \
  -d '{
    "lastLocationCheckinId": "checkin_987",
    "lastLocationLat": 40.7128,
    "lastLocationLng": -74.006,
    "lastLocationAccuracyMeters": 12.4,
    "lastLocationSource": "site_checkin_activated",
    "lastLocationCapturedAt": "2026-02-18T14:20:00.000Z"
  }'

2) Track check-in lifecycle

Use check-ins to represent movement from planned arrival to active presence and eventual checkout, including geofence and suspicion fields when needed.

Create a check-in

curl -X POST https://api.insp.ac/v1/checkins \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkin-user_123-site_001-20260218" \
  -d '{
    "userId": "user_123",
    "siteId": "site_001",
    "status": "pre_checkin",
    "arrivalWindowStartAt": "2026-02-18T15:00:00.000Z",
    "arrivalWindowEndAt": "2026-02-18T15:30:00.000Z"
  }'

Activate and then close a check-in

curl -X PATCH https://api.insp.ac/v1/checkins/checkin_987 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "coordinates": { "latitude": 40.7128, "longitude": -74.006, "accuracyMeters": 12.4 },
    "checkInAddress": "123 Main St"
  }'

curl -X PATCH https://api.insp.ac/v1/checkins/checkin_987 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "checked_out",
    "checkOutAddress": "123 Main St"
  }'

3) Capture logs and comments

Logs are append-only entries attached to a specific entity. UseentryType to separate comments, status updates, and operational notes.

Create a comment log entry

curl -X POST https://api.insp.ac/v1/logs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: log-checkin_987-comment-1" \
  -d '{
    "entityType": "checkin",
    "entityId": "checkin_987",
    "entryType": "comment",
    "message": "Arrived at site and started walkthrough.",
    "source": "api"
  }'

List logs/comments for an entity

curl -X GET "https://api.insp.ac/v1/logs?entityType=checkin&entityId=checkin_987&limit=50" \
  -H "Authorization: Bearer sk_live_..."

4) Ingest sensor input

Sensor input supports batched ingestion so integrations can forward data from gateways without one request per reading.

Ingest readings in a single request

curl -X POST https://api.insp.ac/v1/sensor-readings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sensor-batch-20260218T1430Z" \
  -d '{
    "readings": [
      {
        "provider": "monnit",
        "sensorExternalId": "ext-temp-01",
        "sensorName": "Boiler Room Temp",
        "siteId": "site_001",
        "metric": "temperature_c",
        "value": 23.5,
        "unit": "C",
        "occurredAt": "2026-02-18T14:29:11.000Z"
      },
      {
        "provider": "monnit",
        "sensorExternalId": "ext-humidity-01",
        "siteId": "site_001",
        "metric": "humidity_pct",
        "value": 44.2,
        "unit": "%",
        "occurredAt": "2026-02-18T14:29:11.000Z"
      }
    ]
  }'

Query recent sensor readings

curl -X GET "https://api.insp.ac/v1/sensor-readings?siteId=site_001&occurredAfter=2026-02-18T14:00:00.000Z&limit=100" \
  -H "Authorization: Bearer sk_live_..."

Operational guidance

Tip

Use idempotency keys for all write operations in this workflow to make retries safe across network timeouts and worker restarts.

Note

Keep scope assignment split by integration role: read-only dashboards can use read scopes, while ingestion jobs need write scopes only for the resources they modify.

For implementation details and full schema shapes, use the interactive reference and OpenAPI contract as source-of-truth.