Skip to content

API Documentation

Jump to bottom
Alireza Ahmadi edited this page Feb 5, 2025 · 2 revisions

API Documentation

S-UI supports two types of API services:

  1. Frontend API (/api): Designed for frontend applications, utilizing login-based session and cookie management.
  2. REST API with Token (/apiv2): Used for external applications requiring authentication via API tokens.

This documentation focuses on using the REST API with Token (/apiv2).

Authentication

To interact with the REST API, authentication is required. Follow these steps to obtain and use an API token:

Generating an API Token

  1. Navigate to the Admin page.
  2. Create a new API Token.
  3. For security purposes, set an expiration date and rotate tokens periodically.
  4. Copy and securely store the generated token, as it will not be shown again.

Using the API Token

Include your token in the request header as shown in the example below:

curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/inbounds?id=2"

Response Structure

Every API response follows a consistent format:

{
  "success": true,   // Success status (true or false)
  "msg": "",         // Message if the action fails or is known
  "obj": <obj>       // The data requested or the result after an action
}
  • success: A boolean indicating whether the request was successful or not. It is true if the operation was successful, otherwise false.
  • msg: A message describing the result of the operation. If the request was successful, this is typically an empty string. If failed, it provides an error message or additional information.
  • obj: The object containing the data requested or the result of the action. This can vary depending on the endpoint but will always return relevant data or null if there's no data to return.

For example, a successful response from the /apiv2/save endpoint might look like this:

{
  "success": true,
  "msg": "save",
  "obj": {
    // ... some data ...
  }
}

A failure response, such as for an invalid API token, might look like this:

{
  "success": false,
  "msg": "Invalid token",
  "obj": null
}

API Endpoints

POST Endpoints

Endpoint Description Request Parameters
POST /apiv2/save Save configuration data object (string), action (string), data (JSON), initUsers (optional string)
POST /apiv2/restartApp Restart the application None
POST /apiv2/restartSb Restart the Core None
POST /apiv2/linkConvert Convert a link link (string)
POST /apiv2/importdb Import a database file db (file)

Example usage for POST /apiv2/save:

curl -X POST -H "Token: <Your Token Key>" -d "{...}" "http://localhost:2095/app/apiv2/save"

GET Endpoints

Endpoint Description Query Parameters
GET /apiv2/load Load full data lu (string): Last update timestamp
GET /apiv2/inbounds Get inbound object(s) id (string, optional): Specific inbound ID
GET /apiv2/outbounds Get outbound objects none
GET /apiv2/endpoints Get endpoint objects none
GET /apiv2/tls Get tls objects none
GET /apiv2/clients Get client objects id (string, optional): Specific client ID
GET /apiv2/config Get config objects none
GET /apiv2/users Retrieve user list none
GET /apiv2/settings Get app settings none
GET /apiv2/stats Get statistical data resource (string), tag (string), limit (integer, default: 100)
GET /apiv2/status Get server status r (string): Status request type
GET /apiv2/onlines Get online lists none
GET /apiv2/logs Retrieve server logs c (integer): Number of logs to retrieve, l (string): Log level
GET /apiv2/changes Get user changes a (string, optional): actor name, k (string, optional): key, c (integer) limit
GET /apiv2/keypairs Get keypairs k (string): ech
GET /apiv2/getdb Download the database file exclude (string): Fields to exclude

Example usage for GET /apiv2/status:

curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/status?r=cpu,ram"

** This document is still in progress **

Clone this wiki locally