Remote Unlock API Documentation

Version: 1.0

This document is the official API reference for the Remote Unlock Module. It provides detailed information for all available endpoints, including authentication methods, request parameters, and expected response formats.

Disclaimer

The information provided by this [Website/Document/Service/Product] (hereinafter “the Service”) is for general informational purposes only. All information is provided in good faith, however, we make no representation or warranty of any kind, express or implied, regarding the accuracy, adequacy, validity, reliability, availability, or completeness of any information on the Service.

Under no circumstance shall we have any liability to you for any loss or damage of any kind incurred as a result of the use of the Service or reliance on any information provided on the Service. Your use of the Service and your reliance on any information on the Service is solely at your own risk.

The Service may contain (or you may be sent through the Service) links to other websites or content belonging to or originating from third parties. Such external links are not investigated, monitored, or checked for accuracy, adequacy, validity, reliability, availability, or completeness by us.

The content provided by this Service does not constitute professional advice of any kind (including but not limited to legal, financial, medical, or other professional advice). All content is for informational purposes only. Before taking any action based upon such information, we strongly encourage you to consult with the appropriate professionals. We do not provide any kind of professional advice.

Quick Start

Base URL

The base URL for all API requests is as follows:

1
http://localhost:2091/api/v1

Or:

1
https://localhost:2091/api/v1

The SSL certificate is auto-generated on startup.

Authentication

Most endpoints in this API require authentication via an API key. Please include the Authorization field in the HTTP request header.

  • Type: apiKey
  • Header Field Name: Authorization
  • Format: Authorization: Bearer <YOUR_API_KEY>

Note: <YOUR_API_KEY> needs to be replaced with the actual authentication token you obtained upon login or from the system configuration. All endpoints that require authentication must carry this header, otherwise, a 401 Unauthorized error will be returned.

Common Response Format

All API responses follow a unified data structure to facilitate standardized client-side processing.

1
2
3
4
5
6
{
    "code": 0,
    "msg": "success",
    "data": {},
    "request_id": "unique-request-id-string"
}
  • code: A status code. 0 usually indicates success, while other non-zero values represent different types of errors.
  • msg: A brief description of the response, such as “success” or a specific error message.
  • data: The actual data payload returned, which can be an object, an array, or null.
  • request_id: A unique identifier for this request, which can be used for troubleshooting.

API Endpoint Details

PC Control

POST /control-pc/{action}/

Controls the computer to perform a specified action, such as shutdown, standby, or lock.

  • Authentication: ✅Required
  • Description: Controls the computer based on the action parameter. The shutdown and standby actions can also include a delay time.

Path Parameters

Parameter NameTypeRequiredEnum ValuesDescription
actionstringYesshutdown, standby, lockThe type of action to perform. Respectively: shutdown, standby, lock.

Query Parameters

Parameter NameTypeRequiredDescription
delaystringYesThe delay time in seconds before execution. Only valid when action is shutdown or standby.
shutdown_typestringNoThe type of shutdown. Only effective when action=shutdown. For example, it can be specified as “force” or “hybrid” (see below for available values).
shutdown_typeDescription
0No operation
General
1Log off the current user
2Force close all applications and shut down
3Force close all applications and restart
Windows Only
4Shut down but do not power off
5Restart the computer
6Force close all applications
7Shut down and power off
8Restart applications
9Hybrid shutdown
10Force close applications, shut down, and power off
11Restart the computer and restart applications
12Force close applications, restart, and restart applications
13Shut down without powering off, then restart applications after shutdown
14Hybrid shutdown and force close applications
15Hybrid shutdown and restart applications
16Hybrid shutdown, force close applications, and restart applications

Responses

  • 200 OK: The command was sent successfully.
  • 400 Bad Request: Invalid action type (action is not in the enum list).
  • 500 Internal Server Error: Failed to execute the action, possibly due to insufficient permissions or other system errors.

System

GET /info

Gets basic information about the software, such as its version.

  • Authentication: ✅Required

Responses

  • 200 OK: Successfully retrieved information.
  • 500 Internal Server Error: Internal server error.

GET /info/check_update

Checks if there are any available updates for the system.

  • Authentication: ✅Required
  • Description: Returns details of the latest available update, including the version number, update URL, and release notes.

Query Parameters

Parameter NameTypeRequiredDefault ValueDescription
langstringNoenSpecifies the language for the update information.

Responses

  • 200 OK: Successfully retrieved update information.
  • 500 Internal Server Error: Internal server error.

GET /info/language

Gets the currently configured system language.

  • Authentication: ❌Not Required

Responses

  • 200 OK: Successfully retrieved the language setting.
  • 500 Internal Server Error: Internal server error.

PATCH /info/language

Sets the system language.

  • Authentication: ❌Not Required

Query Parameters

Parameter NameTypeRequiredDefault ValueDescription
langstringNoenThe target language to set.

Responses

  • 200 OK: Language successfully set.
  • 500 Internal Server Error: Internal server error.

GET /logs/{module}

Gets a real-time stream of system logs.

  • Authentication: ✅Required
  • Description: This endpoint establishes a long-lived connection to push system logs in real-time. The connection will remain open until closed by the client or an error occurs.

Path Parameters

Parameter NameTypeRequiredDescription
modulestringYesSpecifies which module’s logs to retrieve. In this document, the value must be service.

Responses

  • 200 OK: Starts pushing the log stream (Content-Type: text/event-stream).
  • 400 Bad Request: An invalid module was specified.
  • 500 Internal Server Error: Internal server error, e.g., the log buffer is unavailable.

Power Saving

POST /power-saving

Enables, disables, or sets power-saving mode to auto.

  • Authentication: ✅Required
  • Description: This function first writes the setting to the database. If the write is successful, it then applies the setting to the system. The value in the database will be updated even if the system application fails.

Query Parameters

Parameter NameTypeRequiredDefault ValueDescription
modestringNoautoPower saving mode. Possible values are enable, disable, or auto.

Responses

  • 200 OK: Power saving mode set successfully.
  • 400 Bad Request: Invalid request parameters.
  • 500 Internal Server Error: Internal server error.

GET /power-saving/status

Gets the current status of the power-saving mode.

  • Authentication: ✅Required

Responses

  • 200 OK: Successfully retrieved the power-saving mode status.
  • 500 Internal Server Error: Internal server error.

Network Interfaces

GET /interface

Gets a list of active network interfaces.

  • Authentication: ✅Required
  • Description: Returns a list of all active network interfaces on the current device, based on the specified IP version (IPv4 or IPv6).

Query Parameters

Parameter NameTypeRequiredDefault ValueEnum ValuesDescription
typestringNo44, 6IP protocol version. 4 for IPv4, 6 for IPv6.

Responses

  • 200 OK: Successfully returned the list of network interfaces.
  • 400 Bad Request: Incorrect request parameters.
  • 500 Internal Server Error: Internal server error.

GET /interface/{ip}

Gets the MAC address corresponding to an IP address.

  • Authentication: ✅Required

Path Parameters

Parameter NameTypeRequiredDescription
ipstringYesThe IP address to query.

Responses

  • 200 OK: Successfully retrieved the MAC address.
  • 400 Bad Request: Invalid request format (e.g., invalid IP address).
  • 500 Internal Server Error: Internal server error.

GET /interface/{ip}/all

Gets complete interface information for an IP address.

  • Authentication: ✅Required

Path Parameters

Parameter NameTypeRequiredDescription
ipstringYesThe IP address to query.

Responses

  • 200 OK: Successfully retrieved interface information.
  • 400 Bad Request: Invalid request format.
  • 500 Internal Server Error: Internal server error.

User Authentication & Operations

POST /login

User login.

  • Authentication: ✅Required (This might refer to basic client authentication to exchange for a longer-lived token)
  • Description: Authenticates using a username and password. On success, it returns a JWT (JSON Web Token) to be used for subsequent authenticated API requests.

Request Body

1
2
3
4
{
    "username": "your_username",
    "password": "your_password"
}
  • Schema: LoginRequest

Responses

  • 200 OK: Authentication successful. The data field of the response will contain the JWT Token.
  • 400 Bad Request: Invalid request parameters (e.g., empty username or password).
  • 500 Internal Server Error: Internal server error.

POST /unlock

Unlock your computer.

  • Authentication: ❌Not Required
  • Description: Sends the computer’s username and password to perform the unlock operation.

Request Body

1
2
3
4
{
    "username": "your_pc_username",
    "password": "your_pc_password"
}
  • Schema: PcUserInfo

Responses

  • 200 OK: Unlock successful.
  • 400 Bad Request: Invalid request format.
  • 500 Internal Server Error: Internal error (e.g., incorrect username or password, unlock failed).

Miscellaneous

GET /ping

Service health check (Ping).

  • Authentication: ❌Not Required
  • Description: Used to check if the service is running correctly, or the status of specific sub-services (like WebSocket).

Query Parameters

Parameter NameTypeRequiredEnum ValuesDescription
typestringNows, pairingThe type of probe. ws might be for testing the WebSocket service, pairing for the pairing service.

Responses

  • 200 OK: Service is OK.
  • 500 Internal Server Error: Service is not available.

Data Models (Definitions)

LoginRequest

The credentials object used for user login.

Field NameTypeRequiredDescription
usernamestringYesUsername
passwordstringYesPassword

PcUserInfo

The user information object used to unlock the computer.

Field NameTypeRequiredDescription
usernamestringNoThe computer’s username
passwordstringNoThe computer’s login password

ResponseData

The common data structure for all API responses.

Field NameTypeDescription
codeintegerBusiness status code, 0 indicates success
dataobjectThe actual returned data
msgstringA message providing details
request_idstringThe unique ID for this request