IR WIKI

Inception REST API

3 min read

Inception REST API

Overview

The Inception REST API (introduced in v3.0.0) allows third-party applications to integrate with Inception controllers. It supports user management, item state monitoring, and control of system entities like Areas, Doors, and outputs.

Technical Details

Key Features

  1. User Management: Remote adding, deleting, and updating of users and credentials.
  2. Live Item State: Real-time monitoring of Areas, Doors, Inputs, Outputs, and Lift Floors using Long Polling.
  3. Item Control: Control commands for arming/disarming areas, unlocking doors, and toggling outputs.

Protocol and Versions

  • The current documentation refers to Protocol v8 (Firmware 4.0) and later.
  • Specific features like User Photos (v8) and PIN Generation (v11) are version-dependent.
  • Query GET /api/protocol-version to check compatibility.

Authentication

  • Method: POST to api/v1/authentication/login with JSON credentials.
  • Session Management: Returns a UserID. This must be included in the Cookie header as LoginSessId=[UserID].
  • Timeout: Sessions expire after 10 minutes of inactivity. Each authenticated request refreshes the timer.
  • Alternative: If Cookie headers cannot be modified, append ?session-id=[UserID] as a query string parameter to any API request.

SkyTunnel Integration

  • The API is accessible globally via SkyTunnel if enabled in [Configuration > General > Network].
  • URL Format: https://www.skytunnel.com.au/inception/[serial]/api/v1/...
  • Note: Clients must handle 307 Redirect responses, as controllers may migrate between SkyTunnel instances.

Configuration / Programming

Setup Steps

  1. API User: Create a dedicated user in the Inception web interface.
  2. Profile: Set the Web Page Profile to REST Web API User.
  3. Credentials: Enable “Web Login” and set a username/password.
  4. Permissions: Assign permissions for the specific Areas, Doors, or Outputs the API needs to interact with.

Documentation and Tools

  • On-board Docs: Accessible at http://[InceptionURL]/ApiDoc or ApiDocExamples.
  • Postman: Inner Range provides a Postman Collection and Environment files (downloadable from the Inception unit) for testing.
  • Detailed Events: Enable “Detailed Events” in [System > Service] to log HTTP requests and failure codes (401, 403, 404, 500) for debugging.

Common Endpoints

Monitoring (Long Polling)

Uses POST /api/v1/monitor-updates. The server holds the request for up to 60 seconds or until a state change occurs.

  • MonitorEntityStates: For Areas, Users, etc.
  • ActivityProgress: To track the status of an arming or control activity.
  • LiveReviewEvents: For real-time event streaming.

Item Control

  • Areas: POST /api/v1/control/area/[id]/activity (e.g., {"Type": "ControlArea", "AreaControlType": "Arm"}).
  • Outputs: POST /api/v1/control/output/[id]/activity.

User Management

  • GET /api/v1/config/user: List users (supports modifiedSince filtering).
  • POST /api/v1/config/user: Create user.
  • PUT /api/v1/config/user/[id]: Full overwrite (omitted fields reset to defaults).
  • PATCH /api/v1/config/user/[id]: Partial update.
  • DELETE /api/v1/config/user/[id]: Delete user.
  • POST /api/v1/config/user/[id]/photo: Upload user photo (Multipart/form-data, v8+).
  • DELETE /api/v1/config/user/[id]/photo: Delete user photo (v8+).
  • GET /api/v1/config/user/generate-unused-pin: Generate an unused PIN (v11+, supports minLength/maxLength query params).

Activities

  • POST /api/v1/activities: Virtually present a credential or PIN at a reader.
    • Credential: {"Type": "CardData", "CardData": {"CredentialTemplateId": "...", "CredentialNumber": "..."}, "ReaderId": "..."}
    • PIN: {"Type": "PIN", "PIN": "1234", "ReaderId": "..."}

Review Events

  • GET /api/v1/review: Query historical events. Supports limit, offset, dir (asc/desc), start/end date filtering, categoryFilter, messageTypeIdFilter, and involvedEntityIdFilter.
  • POST /api/v1/monitor-updates with LiveReviewEvents: Real-time event streaming from a reference event ID.

Troubleshooting

  • 401 Unauthorized: Invalid or expired session ID.
  • 403 Forbidden: API User lacks permission for the requested entity or action.
  • 404 Not Found: Incorrect URL or entity ID.
  • 500 Internal Server Error: Unexpected server-side issue.

Graph View

Backlinks