System Log

The APIs here are designed for system log management.

Topic Reference

Parameter	Description
all	Fetch all logs.
door_openings	Fetch door opening logs.
critical	Fetch logs for device restart, deletion, offline status, and detection.
updates	Fetch device update logs.
device_events	Fetch logs for device online status, device updates, access policy synchronization, and active and inactive door unlock schedules.
admin_activity	Fetch logs for admin activity, such as access policy updates, settings changes, and user management.
visitor	Fetch logs of of visitor-related operations.

Event Structure

Event: Basic information about the event.

Key	Value (Example)
Type	access.door.unlock
Display Message	Access Granted (Remote)
Result	ACCESS
Published	1701087091000
Tag	access

Actor: Information about the event operator.

Key	Value
ID	[Actor ID]
Type	user
Display Name	[Display Name]
Alternate ID	[Alternate ID]
Alternate Name	[Alternate Name]
Avatar	[Avatar]
SSO Picture	[SSO Picture]

Authentication: Certification information.

Key	Value
Credential Provider	REMOTE_THROUGH_UAH
Issuer	[Issuer]

Target(s): Additional information associated with the event. Note that each event contains different attributes.

Type	ID	Display Name	Alternate ID	Alternate Name
UAH	7483c2773855	UA-HUB-3855	[Alternate ID]	[Alternate Name]
device_config	door_entry_method	entry/exit	[Alternate ID]	[Alternate Name]
door	e4978b83-203d-4015-97df-b86efc91cb0c	Door 3855	[Alternate ID]	[Alternate Name]
floor	04ddb371-457f-44ae-b8cc-8e96bcee5de4	1F	[Alternate ID]	[Alternate Name]
building	e622671e-89a5-11ee-8897-76acb95e28d5	UDM Pro	[Alternate ID]	[Alternate Name]

Fetch System Logs

This API enables you to fetch system logs.

Request URL: /api/v1/developer/system/logs
Permission Key: view:system_log
Method: POST

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Token required for authentication and access control.

Query Parameters

Parameter	Required	Type	Description	Example
page_num	F	String	Current page number in the pagination.	1
page_size	F	String	Number of logs per page.	25

Request Body

Parameter	Required	Type	Description	Example
topic	T	String	Fetch different system logs by topic enum topic{critical, door_openings, updates, device_events, admin_activity, visitor}	door_openings
since	F	Integer	Start time for log fetching.	1689304925
until	F	Integer	End time for log fetching.	1689804925
actor_id	F	String	Identity ID of the actor (user, visitor, and device).	3e1f196e-c97b-4748-aecb-eab5e9c251b2

Response Body

Parameter	Required	Type	Description
actor	T	Object	Information about the event operator.
event	T	Object	Basic information about the event.
authentication	F	Object	Certification information.
target	F	Array[Object]	Additional information associated with the event, such as updated information.

Request Sample: Shell/cURL

bash

curl '{host}/api/v1/developer/system/logs?page_size=1&page_num=25'
-H 'Authorization: Bearer wHFmHR*****kD6wHg'
-H 'accept: application/json'
-H 'content-type: application/json'
--data {
    "topic": "door_openings",
    "since": 1690770546,
    "until": 1690771546,
    "actor_id": "3e1f196e-c97b-4748-aecb-eab5e9c251b2"
}

Response Body

json

{
  "code": "SUCCESS",
  "data": {
    "hits": [
      {
        "@timestamp": "2023-07-11T12:11:27Z",
        "_id": "",
        "_source": {
          "actor": {
            "alternate_id": "",
            "alternate_name": "",
            "display_name": "N/A",
            "id": "",
            "type": "user"
          },
          "authentication": {
            "credential_provider": "NFC",
            "issuer": "6FC02554"
          },
          "event": {
            "display_message": "Access Denied / Unknown (NFC)",
            "published": 1689077487000,
            "reason": "",
            "result": "BLOCKED",
            "type": "access.door.unlock"
          },
          "target": [
            {
              "alternate_id": "",
              "alternate_name": "",
              "display_name": "UA-HUB-3855",
              "id": "7483c2773855",
              "type": "UAH"
            }
          ]
        },
        "tag": "access"
      }
    ],
    "page": 1,
    "total": 4
  }
}

Export System Logs

This API enables you to export system logs to a CSV file.

Request URL: /api/v1/developer/system/logs/export
Permission Key: view:system_log
Method: POST
UniFi Access Requirement: 1.20.11 or later

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Token required for authentication and access control.

Request Body

Parameter	Required	Type	Description	Example
topic	T	String	Fetch different system logs by topic enum topic {critical, door_openings, updates, device_events, admin_activity, visitor}	door_openings
since	T	Integer	Start time for log fetching.	1689304925
until	T	Integer	End time for log fetching. Note that the since and until periods cannot exceed one month.	1689804925
timezone	T	String	Timezone for formatting time.	America/New_York
actor_id	F	String	Identity ID of the actor (user, visitor, and device).	3e1f196e-c97b-4748-aecb-eab5e9c251b2

Request Sample: Shell/cURL

bash

curl '{host}/api/v1/developer/system/logs/export'
-H 'Authorization: Bearer wHFmHR*****kD6wHg'
-H 'accept: application/json'
-H 'content-type: application/json'
--data {}
    "topic": "door_openings",
    "since": 1690770546,
    "until": 1690771546,
    "timezone": "America/New_York",
    "actor_id": "3e1f196e-c97b-4748-aecb-eab5e9c251b2"
}'
--insecure

Fetch Resources in System Logs

This API enables you to fetch the resources in system logs.

Request URL: /api/v1/developer/system/logs/resource/:id
Permission Key: view:system_log
Method: GET
UniFi Access Requirement: 1.24.6 or later

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Token required for authentication and access control.

Request Body

Parameter	Required	Type	Description	Example
Id	T	String	Resource ID is obtained from targets categorized as the 'activities_resource' type in system logs.	"target": {"type": "activities_resource","id": "0418d6a38f00-b6906057-2a90-4426-835c-b5b172381fec","display_name": "Resource","alternate_id": "", "alternate_name": ""}]

Response Sample

json

{
  "code": "SUCCESS",
  "msg": "success",
  "data": {
    "video_record": "/activities_resource/video/1708424638_f24a7b67-c584-4e22-a7b8-074f0fa93da0.mp4",
    "video_record_thumbnail": "/activities_resource/thumbnail/1708424638_a6d1fa60-d895-4d4c-a40c-447f97c8824f.jpg",
    "created_at": "2024-02-20T18:23:58+08:00",
    "updated_at": "2024-02-20T18:23:58+08:00"
  }
}

Request Sample: Shell/cURL

bash

curl '{host}/api/v1/developer/system/logs/resource/0418d6a38f00-b6906057-2a90-4426-835c-b5b172381fec'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Fetch Static Resources in System Logs

This API enables you to fetch static resources in system logs.

Request URL: /api/v1/developer/system/static/:path
Permission Key: view:system_log
Method: GET
UniFi Access Requirement: 1.24.6 or later

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Token required for authentication and access control.

Request Body

Parameter	Required	Type	Description	Example
path	T	String	Resource paths, currently supporting /ayar, /capture, and activities_resource.

yaml

### avatar resource
curl '{host}/api/v1/developer/system/static/ avatar/dalaceb6-20ba-4285-a6b1-c4f2bf7161f8'
-H 'Authorization: Bearer wHFmHR*****kD6wHg'
-H 'accept: application/json'
-H 'content-type: application/json'
--insecure
### preview resource
curl '{host}/api/v1/developer/system/static-preview/1700707333_9660da3a-06c8-459d-8cc9-24889d13fba5.png'
-H 'Authorization: Bearer wHFmHR*****kD6wHg'
-H 'accept: application/json'
-H 'content-type: application/json'
--insecure
### capture video resource
curl '{host}/api/v1/developer/system/static/activities_resource/video/1708402379_92746868-5c69-4a11-9d4c-33f03785d741.jpg'
-H 'Authorization: Bearer wHFmHR*****kD6wHg'
-H 'accept: application/json'
-H 'content-type: application/json'
--insecure
### capture thumbnail resource
curl
'{host}/api/v1/developer/system/static/activities_resource/thumbail/1708402379_92746868-5c69-4a11-9d4c-33f03785d741.jpg'
-H 'Authorization: Bearer wHFmHR*****kD6wHg'
-H 'accept: application/json'
-H 'content-type: application/json'
--insecure

/access_policies

/nfc_cards

/delete

/pin_codes

/license_plates

/avatar

/identity/assignments

/touch_passes/{touch_pass_id}

/license_plates/{license_plate_id}

/invitations

/assignments

/users

/delete

/all

/access_policies

/identity/assignments

/nfc_cards

/delete

/pin_codes

/qr_codes

/license_plates

/{id}

/{id}

/sessions

/{id}

/tokens

/{token}

/import

/search

/assignable

/{id}

/unlock

/lock_rule

/settings

/doorbell

/export

/resource/{id}

System Log ​

Topic Reference ​

Event Structure ​

Fetch System Logs ​

Request Header ​

Query Parameters ​

Request Body ​

Response Body ​

Response Body ​

Export System Logs ​

Request Header ​

Request Body ​

Request Sample: Shell/cURL ​

Fetch Resources in System Logs ​

Request Header ​

Request Body ​

Response Sample ​

Request Sample: Shell/cURL ​

Fetch Static Resources in System Logs ​

Request Header ​

Request Body ​

System Log

Topic Reference

Event Structure

Fetch System Logs

Request Header

Query Parameters

Request Body

Response Body

Response Body

Export System Logs

Request Header

Request Body

Request Sample: Shell/cURL

Fetch Resources in System Logs

Request Header

Request Body

Response Sample

Request Sample: Shell/cURL

Fetch Static Resources in System Logs

Request Header

Request Body