### Install latest stable version

Source: https://docs.sanaei.dev/docs/guide/installation

Run the official script installer as root or with sudo. It generates random credentials, sets up the service, and installs the x-ui management command.

```bash
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
```

--------------------------------

### GET /panel/api/server/getXrayVersion

Source: https://docs.sanaei.dev/docs/reference/api/server

Lists Xray binary versions available for installation on the host.

```APIDOC
## GET /panel/api/server/getXrayVersion

### Description
Lists Xray binary versions available for installation on the host.

### Method
GET

### Endpoint
`/panel/api/server/getXrayVersion`

### Authorization
`bearerAuth` - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>` in the header.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **obj** (array of strings) - List of available Xray versions.

#### Response Example
```json
{
  "success": true,
  "obj": [
    "v25.10.31",
    "v25.9.15",
    "v25.8.1"
  ]
}
```
```

--------------------------------

### Response body for GET /panel/api/server/getNewX25519Cert

Source: https://docs.sanaei.dev/docs/reference/api/server

Example 200 response containing the generated private and public keys.

```json
{
  "success": true,
  "obj": {
    "privateKey": "uN9qLfV3zH8w...",
    "publicKey": "5v8xPqR2sM7k..."
  }
}
```

--------------------------------

### Start Docker with PostgreSQL profile

Source: https://docs.sanaei.dev/docs/reference/database

Command to start 3x-ui with the bundled PostgreSQL service. Uncomment the two XUI_DB_* lines in docker-compose.yml and use the postgres profile.

```bash
docker compose --profile postgres up -d
```

--------------------------------

### GET getWebCertFiles - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Example successful response for the getWebCertFiles endpoint, showing certificate and key file paths.

```json
{
  "success": true,
  "obj": {
    "webCertFile": "/root/cert/example.com/fullchain.pem",
    "webKeyFile": "/root/cert/example.com/privkey.pem"
  }
}
```

--------------------------------

### Install rolling dev build

Source: https://docs.sanaei.dev/docs/guide/installation

Pass dev-latest to install the latest per-commit pre-release from main, not a stable release.

```bash
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
```

--------------------------------

### Unattended install with XUI_NONINTERACTIVE

Source: https://docs.sanaei.dev/docs/guide/installation

Set XUI_NONINTERACTIVE=1 to run the installer non-interactively with zero prompts. It generates random credentials and writes them to /etc/x-ui/install-result.env.

```bash
XUI_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
```

--------------------------------

### JSON subscription URL example

Source: https://docs.sanaei.dev/docs/config/subscription

An example of a generated JSON subscription URL.

```text
https://sub.example.com:2096/your-json-path/user-1
```

--------------------------------

### GET getXrayVersion - cURL request

Source: https://docs.sanaei.dev/docs/reference/api/server

Lists Xray binary versions available for install on the host. Requires a bearer token in the Authorization header.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/getXrayVersion" \
  -H "Authorization: Bearer "
```

--------------------------------

### POST /panel/api/setting/defaultSettings - Get computed default settings

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns the computed default settings based on the request host, useful to preview what a fresh install would use. Requires a logged-in session or Bearer token. The response body is shown for a 200 status.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/setting/defaultSettings" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### Base64 subscription URL example

Source: https://docs.sanaei.dev/docs/config/subscription

An example of a generated Base64 subscription URL.

```text
https://sub.example.com:2096/your-sub-path/user-1
```

--------------------------------

### Install Xray Version (cURL)

Source: https://docs.sanaei.dev/docs/reference/api/server

Sends a POST request to download and install a specified Xray version. The version path parameter accepts a tag like v25.10.31 or "latest". Requires an Authorization header with a bearer token.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/server/installXray/string" \
  -H "Authorization: Bearer "
```

--------------------------------

### Install pinned version v3.4.0

Source: https://docs.sanaei.dev/docs/guide/installation

Append a version tag to the install command to install a specific version.

```bash
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
```

--------------------------------

### Install and issue certificate with Certbot standalone

Source: https://docs.sanaei.dev/docs/config/ssl-certificates

Install Certbot and issue a standalone certificate for yourdomain.com. Requires port 80 free and the domain resolving to the server. The dry-run renewal verifies the renewal process.

```bash
apt-get install certbot -y
certbot certonly --standalone --agree-tos --register-unsafely-without-email -d yourdomain.com
certbot renew --dry-run
```

--------------------------------

### Response body for GET /panel/api/server/descendants

Source: https://docs.sanaei.dev/docs/reference/api/server

Example 200 response showing a successful retrieval with an array of node summaries.

```json
{
  "success": true,
  "obj": [
    {
      "guid": "c3d4-...",
      "parentGuid": "a1b2-...",
      "name": "Node3",
      "address": "10.0.0.3",
      "status": "online"
    }
  ]
}
```

--------------------------------

### POST /panel/api/server/installXray/{version}

Source: https://docs.sanaei.dev/docs/reference/api/server

Downloads and installs the specified Xray version. Pass "latest" for the newest release. Requires bearer token authentication.

```APIDOC
## POST /panel/api/server/installXray/{version}

### Description
Downloads and installs the specified Xray version. Pass "latest" for the newest release.

### Method
POST

### Endpoint
/panel/api/server/installXray/{version}

### Parameters
#### Path Parameters
- **version** (string) - Required - Xray tag (e.g. v25.10.31) or "latest".

#### Authorization
- **Authorization** (header) - Required - Bearer token. API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **msg** (string) - Message describing the result.
- **obj** (null) - Additional data (null in this case).

#### Response Example
```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

### Request Example
```bash
curl -X POST "https://docs.sanaei.dev/panel/api/server/installXray/string" \
  -H "Authorization: Bearer "
```
```

--------------------------------

### GET getXrayVersion - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Example successful response for the getXrayVersion endpoint. The response includes a success flag and an array of version strings.

```json
{
  "success": true,
  "obj": [
    "v25.10.31",
    "v25.9.15",
    "v25.8.1"
  ]
}
```

--------------------------------

### PostgreSQL environment configuration in /etc/default/x-ui

Source: https://docs.sanaei.dev/docs/reference/database

Environment variables that select the PostgreSQL backend at runtime. The installer writes these to /etc/default/x-ui. Tune the connection pool with XUI_DB_MAX_OPEN_CONNS and XUI_DB_MAX_IDLE_CONNS.

```bash
XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
```

--------------------------------

### Response: Get last N lines of panel log

Source: https://docs.sanaei.dev/docs/reference/api/server

Example 200 response for the logs endpoint, showing an array of log lines.

```json
{
  "success": true,
  "obj": [
    "2025/01/01 12:00:00 [INFO] Server started",
    "2025/01/01 12:00:01 [INFO] Xray is running"
  ]
}
```

--------------------------------

### List all subscription balancers - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/subscription-balancers

Example 200 response for the GET /panel/api/sub-balancers endpoint, showing a balancer object with fields like createdAt, enabled, id, inboundIds, memberWeights, remark, sortOrder, strategy, and updatedAt.

```json
{
  "success": true,
  "obj": [
    {
      "createdAt": 1710000000000,
      "enabled": true,
      "id": 1,
      "inboundIds": [
        1,
        3
      ],
      "memberWeights": {},
      "remark": "auto-fastest",
      "sortOrder": 1,
      "strategy": "random",
      "updatedAt": 1710000000000
    }
  ]
}
```

--------------------------------

### POST /panel/api/setting/defaultSettings

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns the computed default settings based on the request host. Useful to preview what a fresh install would use.

```APIDOC
## POST /panel/api/setting/defaultSettings

### Description
Returns the computed default settings based on the request host. Useful to preview what a fresh install would use.

### Method
POST

### Endpoint
/panel/api/setting/defaultSettings

### Parameters
#### Authorization
- **bearerAuth** (header) - Required - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Request Example
```
curl -X POST "https://docs.sanaei.dev/panel/api/setting/defaultSettings" \
  -H "Authorization: Bearer "
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Response message.
- **obj** (null) - Response object (null in this case).

#### Response Example
```
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
```

--------------------------------

### Run the x-ui interactive menu

Source: https://docs.sanaei.dev/docs/guide/update-uninstall

Run the x-ui command with no arguments to open the interactive management menu. This is the control center after a script install.

```bash
x-ui
```

--------------------------------

### 200 Response for GET /panel/api/hosts/list

Source: https://docs.sanaei.dev/docs/reference/api/hosts

Example 200 response body for the list hosts endpoint. Shows the full host object structure with fields such as allowInsecure, alpn, inboundIds, and security.

```json
{
  "success": true,
  "obj": [
    {
      "allowInsecure": false,
      "alpn": [
        ""
      ],
      "echConfigList": "",
      "excludeFromSubTypes": [
        ""
      ],
      "finalMask": "",
      "fingerprint": "",
      "groupId": "",
      "hostHeader": "",
      "hosts": [
        ""
      ],
      "inboundIds": [
        0
      ],
      "isDisabled": false,
      "isHidden": false,
      "keepSniBlank": false,
      "mihomoIpVersion": "dual",
      "mihomoX25519": false,
      "muxParams": "",
      "nodeGuids": [
        ""
      ],
      "overrideSniFromAddress": false,
      "path": "",
      "pinnedPeerCertSha256": [
        ""
      ],
      "port": 0,
      "remark": "",
      "security": "same",
      "serverDescription": "",
      "shuffleHost": false,
      "sni": "",
      "sockoptParams": "",
      "sortOrder": 0,
      "tags": [
        ""
      ],
      "verifyPeerCertByName": "",
      "vlessRoute": ""
    }
  ]
}
```

--------------------------------

### POST /panel/api/hosts/add - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/hosts

Example successful response for the add host endpoint. Shows the created host object with all its fields.

```json
{
  "success": true,
  "obj": [
    {
      "address": "cdn.example.com",
      "allowInsecure": false,
      "alpn": [
        ""
      ],
      "createdAt": 0,
      "echConfigList": "",
      "excludeFromSubTypes": [
        ""
      ],
      "finalMask": "",
      "fingerprint": "",
      "groupId": "",
      "hostHeader": "",
      "id": 1,
      "inboundId": 1,
      "isDisabled": false,
      "isHidden": false,
      "keepSniBlank": false,
      "mihomoIpVersion": "dual",
      "mihomoX25519": false,
      "muxParams": null,
      "nodeGuids": [
        ""
      ],
      "overrideSniFromAddress": false,
      "path": "",
      "pinnedPeerCertSha256": [
        ""
      ],
      "port": 8443,
      "remark": "cdn-front",
      "security": "same",
      "serverDescription": "",
      "shuffleHost": false,
      "sni": "",
      "sockoptParams": null,
      "sortOrder": 0,
      "tags": [
        ""
      ],
      "updatedAt": 0,
      "verifyPeerCertByName": "",
      "vlessRoute": "443"
    }
  ]
}
```

--------------------------------

### 200 response for scanRealityTarget

Source: https://docs.sanaei.dev/docs/reference/api/server

Example success response showing the feasibility verdict (feasible: true), TLS 1.3, h2, X25519, and certificate details. The serverNames array is empty in this example.

```json
{
  "success": true,
  "obj": {
    "alpn": "h2",
    "certChainBytes": 3427,
    "certChainValid": true,
    "certIssuer": "Google Trust Services",
    "certSubject": "cloudflare.com",
    "certValid": true,
    "curveID": "X25519",
    "feasible": true,
    "h2": true,
    "host": "www.cloudflare.com",
    "ip": "104.16.124.96",
    "latencyMs": 180,
    "notAfter": "2026-08-01T00:00:00Z",
    "port": 443,
    "privateTarget": false,
    "reason": "",
    "serverNames": [
      ""
    ],
    "target": "www.cloudflare.com:443",
    "tls13": true,
    "tlsVersion": "1.3",
    "x25519": true
  }
}
```

--------------------------------

### GET /panel/api/server/getPanelUpdateInfo

Source: https://docs.sanaei.dev/docs/reference/api/server

Checks whether a newer 3x-ui release is available on GitHub.

```APIDOC
## GET /panel/api/server/getPanelUpdateInfo

### Description
Checks whether a newer 3x-ui release is available on GitHub.

### Method
GET

### Endpoint
`/panel/api/server/getPanelUpdateInfo`

### Authorization
`bearerAuth` - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>` in the header.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Response message.
- **obj** (object) - Response data (may be null).

#### Response Example
```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
```

--------------------------------

### GET /panel/api/server/getNewX25519Cert

Source: https://docs.sanaei.dev/docs/reference/api/server

Generates a new X25519 keypair for Reality. Requires bearer token authentication.

```APIDOC
## GET /panel/api/server/getNewX25519Cert

### Description
Generates a new X25519 keypair for Reality.

### Method
GET

### Endpoint
`/panel/api/server/getNewX25519Cert`

### Authorization
- **Type**: bearerAuth
- **Header**: `Authorization: Bearer <token>`
- **Description**: API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Response Body
- **Content-Type**: `application/json`

#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **obj** (object) - Contains the generated keypair.
  - **privateKey** (string) - The private key.
  - **publicKey** (string) - The public key.

#### Response Example
```json
{
  "success": true,
  "obj": {
    "privateKey": "uN9qLfV3zH8w...",
    "publicKey": "5v8xPqR2sM7k..."
  }
}
```
```

--------------------------------

### List all subscription balancers (GET /panel/api/sub-balancers) - cURL

Source: https://docs.sanaei.dev/docs/reference/api/subscription-balancers

Sends a GET request to list all subscription balancers in sort order (sort_order asc, id asc). Requires an API token from Settings → Security → API Token, sent as Authorization: Bearer <token>.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/sub-balancers" \
  -H "Authorization: Bearer "
```

--------------------------------

### GET /panel/api/server/getConfigJson

Source: https://docs.sanaei.dev/docs/reference/api/server

Return the assembled Xray config that’s currently running on this host.

```APIDOC
## GET /panel/api/server/getConfigJson

### Description
Return the assembled Xray config that’s currently running on this host.

### Method
GET

### Endpoint
/panel/api/server/getConfigJson

### Authorization
- **bearerAuth** (header) - Required - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Optional message.
- **obj** (object|null) - The assembled Xray config, or null if not available.

#### Response Example
```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
```

--------------------------------

### GET /panel/api/server/getNewmlkem768

Source: https://docs.sanaei.dev/docs/reference/api/server

Generates a new ML-KEM-768 keypair and returns the seed and client keys.

```APIDOC
## GET /panel/api/server/getNewmlkem768

### Description
Generates a new ML-KEM-768 keypair and returns the seed and client keys.

### Method
GET

### Endpoint
`https://docs.sanaei.dev/panel/api/server/getNewmlkem768`

### Authorization
- **Type**: Bearer token
- **Header**: `Authorization: Bearer <token>`
- **Token source**: Settings → Security → API Token

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **obj.client** (string) - The generated client key.
- **obj.seed** (string) - The generated seed.

#### Response Example
```json
{
  "success": true,
  "obj": {
    "client": "mlkem768-client",
    "seed": "mlkem768-seed"
  }
}
```
```

--------------------------------

### GET /panel/api/server/history/{metric}/{bucket}

Source: https://docs.sanaei.dev/docs/reference/api/server

Returns an array of {t, v} samples covering the last ~6 hours for a specified metric and bucket size.

```APIDOC
## GET /panel/api/server/history/{metric}/{bucket}

### Description
Returns an array of {t, v} samples covering the last ~6 hours for the specified metric and bucket size.

### Method
GET

### Endpoint
`/panel/api/server/history/{metric}/{bucket}`

### Parameters
#### Path Parameters
- **metric** (string) - Required - Metric name. Allowed: cpu, mem, netUp, netDown, online, load1, load5, load15.
- **bucket** (integer) - Required - Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.

### Authorization
`bearerAuth` - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>` in the header.

### Request Example
```
curl -X GET "https://docs.sanaei.dev/panel/api/server/history/string/0" \
  -H "Authorization: Bearer "
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success.
- **obj** (array) - Array of samples, each with:
  - **t** (integer) - Timestamp.
  - **v** (number) - Value.

#### Response Example
```
{
  "success": true,
  "obj": [
    {
      "t": 1700000000,
      "v": 12.5
    },
    {
      "t": 1700000002,
      "v": 13.1
    }
  ]
}
```
```

--------------------------------

### Create a subscription balancer - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/subscription-balancers

Example 200 response for the POST /panel/api/sub-balancers endpoint, showing the created balancer object with the same fields as the list response.

```json
{
  "success": true,
  "obj": {
    "createdAt": 1710000000000,
    "enabled": true,
    "id": 1,
    "inboundIds": [
      1,
      3
    ],
    "memberWeights": {},
    "remark": "auto-fastest",
    "sortOrder": 1,
    "strategy": "random",
    "updatedAt": 1710000000000
  }
}
```

--------------------------------

### Backup response 200 JSON

Source: https://docs.sanaei.dev/docs/reference/api/backup

Example 200 response body for the backup request. Indicates success with a message and a null object.

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### POST /panel/api/xray/ - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Example successful response containing the raw Xray config, inbound tags, client reverse tags, and the outbound test URL.

```json
{
  "success": true,
  "obj": {
    "xraySetting": "{...raw xray config...}",
    "inboundTags": "[\"in-443-tcp\"]",
    "clientReverseTags": "[]",
    "outboundTestUrl": "https://www.google.com/generate_204"
  }
}
```

--------------------------------

### cURL request to GET /panel/api/server/getNewX25519Cert

Source: https://docs.sanaei.dev/docs/reference/api/server

Generates a new X25519 keypair for Reality. Requires an API token sent as Authorization: Bearer <token>.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/getNewX25519Cert" \
  -H "Authorization: Bearer "
```

--------------------------------

### Response: test 200

Source: https://docs.sanaei.dev/docs/reference/api/nodes

Example 200 response for the test endpoint, containing a heartbeat snapshot with metrics like CPU, memory, latency, and panel version.

```json
{
  "success": true,
  "obj": {
    "cpuPct": 12.5,
    "error": "",
    "latencyMs": 42,
    "memPct": 45.2,
    "panelVersion": "v3.x.x",
    "status": "online",
    "uptimeSecs": 86400,
    "xrayError": "",
    "xrayState": "",
    "xrayVersion": "25.10.31"
  }
}
```

--------------------------------

### GET getNewUUID - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Example successful response for the getNewUUID endpoint, containing a sample UUID.

```json
{
  "success": true,
  "obj": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

--------------------------------

### Docker: read credentials from container logs

Source: https://docs.sanaei.dev/docs/guide/first-login

For Docker installations, read the generated credentials from the container logs, or run this command to show settings.

```bash
docker exec -it <container> x-ui setting -show
```

--------------------------------

### Response: getUpdateStatus success

Source: https://docs.sanaei.dev/docs/reference/api/server

Example 200 response for getUpdateStatus. Shows a successful update with exitCode 0, finishedAt timestamp, runId, and state 'success'.

```json
{
  "success": true,
  "obj": {
    "exitCode": 0,
    "finishedAt": 1735689612,
    "runId": "1735689600123456789",
    "state": "success"
  }
}
```

--------------------------------

### Credential summary file /etc/x-ui/install-result.env

Source: https://docs.sanaei.dev/docs/guide/first-login

A script install writes the generated credentials to this root-only file (mode 600). Contains username, password, panel port, web base path, access URL, API token, and DB type.

```text
XUI_USERNAME=...
XUI_PASSWORD=...
XUI_PANEL_PORT=...
XUI_WEB_BASE_PATH=...
XUI_ACCESS_URL=...
XUI_API_TOKEN=...
XUI_DB_TYPE=sqlite
```

--------------------------------

### GET /panel/api/server/cpuHistory/{bucket}

Source: https://docs.sanaei.dev/docs/reference/api/server

Legacy endpoint for aggregated CPU history. It is recommended to use /history/cpu/:bucket instead for a uniform data shape.

```APIDOC
## GET /panel/api/server/cpuHistory/{bucket}

### Description
Legacy: aggregated CPU history. Use /history/cpu/:bucket instead — same data with a uniform {t, v} shape.

### Method
GET

### Endpoint
/panel/api/server/cpuHistory/{bucket}

### Parameters
#### Path Parameters
- **bucket** (integer) - Required - Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Status message.
- **obj** (null) - Data object.

### Response Example
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### POST /panel/api/setting/all - Return all panel settings

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns every panel setting (web server, Telegram bot, subscription, security, LDAP) as a JSON blob. Requires a logged-in session or Bearer token. The response body is shown for a 200 status.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/setting/all" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### Migrate SQLite to PostgreSQL with x-ui migrate-db

Source: https://docs.sanaei.dev/docs/reference/database

Built-in command to migrate an existing SQLite install to PostgreSQL. Provide the DSN to the target PostgreSQL server.

```bash
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable"
```

--------------------------------

### POST /panel/api/server/setUpdateChannel

Source: https://docs.sanaei.dev/docs/reference/api/server

Toggles the panel update channel between stable and the rolling per-commit dev release.

```APIDOC
## POST /panel/api/server/setUpdateChannel

### Description
Toggle the panel update channel between stable and the rolling per-commit dev release. Only effective on dev builds.

### Method
POST

### Endpoint
/panel/api/server/setUpdateChannel

### Parameters
#### Request Body
- **dev** (boolean) - Required - true = dev channel, false = stable.

### Request Example
dev=true

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Status message.
- **obj** (null) - Null object.

#### Response Example
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### GET getPanelUpdateInfo - cURL request

Source: https://docs.sanaei.dev/docs/reference/api/server

Checks whether a newer 3x-ui release is available on GitHub. Requires a bearer token in the Authorization header.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/getPanelUpdateInfo" \
  -H "Authorization: Bearer "
```

--------------------------------

### AmneziaWG client .conf example

Source: https://docs.sanaei.dev/docs/config/amneziawg

Client configuration file for AmneziaWG, used as the downloadable .conf and encoded in the vpn:// share link. Contains interface settings (private key, address, DNS, obfuscation parameters) and a peer section with server public key, allowed IPs, endpoint, and keepalive.

```ini
[Interface]
PrivateKey = <client private key>
Address = 10.8.1.2/32
DNS = 8.8.8.8, 8.8.4.4
Jc = 4
Jmin = 65
Jmax = 220
S1 = 87
S2 = 44
S3 = 21
S4 = 9
H1 = 463065432
H2 = 912345678
H3 = 1345678901
H4 = 1987654321
I1 = <r 148>
HeaderProtectionKey = 8Iu83eHDA3fMKKSGaEsVW9Ycd2lYYzc0MYlk1jJTvE4=
ContentPaddingAddition = 17-49
RekeyAfterTime = 111-139
RekeyTimeout = 4-7
RejectAfterTime = 187-251
KeepaliveTimeout = 9-14
MaxHandshakeAttempts = 19-36
RandomTrailers = on
DisableCookies = on

# my-client
[Peer]
PublicKey = <server public key>
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = your-server:443
PersistentKeepalive = 25
```

--------------------------------

### GET /panel/api/hosts/tags - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/hosts

Example successful response for the tags endpoint. Shows the structure with a success flag and an array of tag strings.

```json
{
  "success": true,
  "obj": [
    "CDN",
    "EU",
    "FAST"
  ]
}
```

--------------------------------

### GET /panel/api/server/fail2banStatus

Source: https://docs.sanaei.dev/docs/reference/api/server

Reports whether per-client IP limits can be enforced on this host. The panel uses it to gate the 'IP Limit' field, since enforcement depends on Fail2ban being installed.

```APIDOC
## GET /panel/api/server/fail2banStatus

### Description
Reports whether per-client IP limits can be enforced on this host. The panel uses it to gate the "IP Limit" field, since enforcement depends on Fail2ban being installed.

### Method
GET

### Endpoint
/panel/api/server/fail2banStatus

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **obj** (object) - Contains status details.
  - **enabled** (boolean) - Whether Fail2ban is enabled.
  - **installed** (boolean) - Whether Fail2ban is installed.
  - **usable** (boolean) - Whether Fail2ban is usable.
  - **windows** (boolean) - Whether the host is running Windows.

### Response Example
{
  "success": true,
  "obj": {
    "enabled": true,
    "installed": true,
    "usable": true,
    "windows": false
  }
}
```

--------------------------------

### GET /panel/api/setting/getDefaultJsonConfig

Source: https://docs.sanaei.dev/docs/reference/api/settings

This endpoint returns the built-in default Xray JSON configuration template that ships with the panel version. It requires bearer token authentication.

```APIDOC
## GET /panel/api/setting/getDefaultJsonConfig

### Description
Returns the built-in default Xray JSON configuration template that ships with this panel version.

### Method
GET

### Endpoint
`/panel/api/setting/getDefaultJsonConfig`

### Authorization
- **Type**: Bearer token
- **Header**: `Authorization: Bearer <token>`
- **Description**: API token from Settings → Security → API Token.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Response message.
- **obj** (null) - The default Xray JSON config template (null in example).

#### Response Example
```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
```

--------------------------------

### GET /panel/api/server/fail2banStatus with cURL and 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Checks whether per-client IP limits can be enforced on this host. The panel uses this endpoint to gate the "IP Limit" field, since enforcement depends on Fail2ban being installed. The response indicates whether Fail2ban is enabled, installed, usable, and whether the host is Windows.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/fail2banStatus" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "obj": {
    "enabled": true,
    "installed": true,
    "usable": true,
    "windows": false
  }
}
```

--------------------------------

### POST /panel/api/setting/all

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns every panel setting: web server, Telegram bot, subscription, security, LDAP. The full JSON blob that the Settings page edits.

```APIDOC
## POST /panel/api/setting/all

### Description
Returns every panel setting: web server, Telegram bot, subscription, security, LDAP. The full JSON blob that the Settings page edits.

### Method
POST

### Endpoint
/panel/api/setting/all

### Parameters
#### Authorization
- **bearerAuth** (header) - Required - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Request Example
```
curl -X POST "https://docs.sanaei.dev/panel/api/setting/all" \
  -H "Authorization: Bearer "
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Response message.
- **obj** (null) - Response object (null in this case).

#### Response Example
```
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
```

--------------------------------

### View current settings with x-ui menu

Source: https://docs.sanaei.dev/docs/guide/first-login

Use the x-ui menu to view current settings (menu option 11) or the one-shot form. Useful if you missed the credential summary.

```bash
x-ui              # menu → 11 (View Current Settings)
x-ui settings     # or the one-shot form
```

--------------------------------

### cURL request to GET /panel/api/server/descendants

Source: https://docs.sanaei.dev/docs/reference/api/server

Retrieves read-only summaries (guid, parentGuid, name, address, status, versions) of descendant nodes. Requires an API token sent as Authorization: Bearer <token>.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/descendants" \
  -H "Authorization: Bearer "
```

--------------------------------

### Response for fetching host group by group ID

Source: https://docs.sanaei.dev/docs/reference/api/hosts

Example 200 response body for the GET /panel/api/hosts/get/{groupId} endpoint. Shows the structure of a host group object with fields like allowInsecure, alpn, hosts, inboundIds, and security.

```json
{
  "success": true,
  "obj": {
    "allowInsecure": false,
    "alpn": [
      ""
    ],
    "echConfigList": "",
    "excludeFromSubTypes": [
      ""
    ],
    "finalMask": "",
    "fingerprint": "",
    "groupId": "",
    "hostHeader": "",
    "hosts": [
      ""
    ],
    "inboundIds": [
      0
    ],
    "isDisabled": false,
    "isHidden": false,
    "keepSniBlank": false,
    "mihomoIpVersion": "dual",
    "mihomoX25519": false,
    "muxParams": "",
    "nodeGuids": [
      ""
    ],
    "overrideSniFromAddress": false,
    "path": "",
    "pinnedPeerCertSha256": [
      ""
    ],
    "port": 0,
    "remark": "",
    "security": "same",
    "serverDescription": "",
    "shuffleHost": false,
    "sni": "",
    "sockoptParams": "",
    "sortOrder": 0,
    "tags": [
      ""
    ],
    "verifyPeerCertByName": "",
    "vlessRoute": ""
  }
}
```

--------------------------------

### GET /panel/api/inbounds/allLinks - Export all inbound links

Source: https://docs.sanaei.dev/docs/reference/api/inbounds

Returns every protocol URL (vless://, vmess://, trojan://, ss://, hysteria://, mtproto) across all inbounds and clients. Links are rendered through the subscription engine, applying the configured remark template per client. Protocols without a URL form (socks, http, mixed, wireguard, dokodemo, tunnel) contribute nothing.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/inbounds/allLinks" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "obj": [
    "vless://uuid@host:443?security=reality&...#Germany-alice",
    "vmess://eyJ2IjoyLC..."
  ]
}
```

--------------------------------

### Client vless:// share link excerpt

Source: https://docs.sanaei.dev/docs/config/reality

Shows the client share link carrying public parameters: pbk (public key), sid, sni, fp, spx, and flow. The flow must be xtls-rprx-vision on both server and client.

```text
vless://<uuid>@<server>:443?security=reality&pbk=<public-key>&sid=<short-id>&sni=www.microsoft.com&fp=chrome&spx=%2F&flow=xtls-rprx-vision#my-reality
```

--------------------------------

### GET /panel/api/xray/outbound-subs with cURL

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to list outbound subscriptions. The response is a JSON object with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/outbound-subs" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### GET /panel/api/xray/geodata/files with cURL

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to list geo database files. The response is a JSON object with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/geodata/files" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### GET /panel/api/xray/getDefaultJsonConfig - cURL request

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to retrieve the built-in default Xray config. Requires a bearer token in the Authorization header.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/getDefaultJsonConfig" \
  -H "Authorization: Bearer "
```

--------------------------------

### Create a subscription balancer (POST /panel/api/sub-balancers) - cURL

Source: https://docs.sanaei.dev/docs/reference/api/subscription-balancers

Sends a POST request to create a subscription balancer. Requires an API token and uses application/x-www-form-urlencoded content type. The request body must include remark and inboundIds (at least one). Optional fields include strategy (default "random"), memberWeights (leastLoad only), sortOrder (default 1), and enabled (default true on create).

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/sub-balancers" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'remark=string&inboundIds=0'
```

--------------------------------

### cURL: Get Xray process output

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to /panel/api/xray/getXrayResult with bearer token authorization. Returns JSON with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/getXrayResult" \
  -H "Authorization: Bearer "
```

--------------------------------

### cURL: Get outbound traffic statistics

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to /panel/api/xray/getOutboundsTraffic with bearer token authorization. Returns JSON with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/getOutboundsTraffic" \
  -H "Authorization: Bearer "
```

--------------------------------

### Restart panel via POST /panel/api/setting/restartPanel

Source: https://docs.sanaei.dev/docs/reference/api/settings

Restarts the entire 3x-ui process after a 3-second grace period. The connection drops immediately; the panel comes back online ~5-10 seconds later.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/setting/restartPanel" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### GET /panel/api/nodes/webCert/{id} - Fetch node web cert paths

Source: https://docs.sanaei.dev/docs/reference/api/nodes

Fetches a node's own web TLS certificate and key file paths. The request requires an API token in the Authorization header. The response contains the paths that exist on the node, not the central panel.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/nodes/webCert/0" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "obj": {
    "webCertFile": "/root/cert/example.com/fullchain.pem",
    "webKeyFile": "/root/cert/example.com/privkey.pem"
  }
}
```

--------------------------------

### List nodes with GET /panel/api/nodes/list

Source: https://docs.sanaei.dev/docs/reference/api/nodes

Lists every configured node with connection details, health metrics, and last heartbeat. Requires an API token sent as `Authorization: Bearer <token>` in the header. Returns a 200 response with a `success` flag and an `obj` array containing node objects.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/nodes/list" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "obj": [
    {
      "activeCount": 20,
      "address": "node.example.com",
      "allowPrivateAddress": false,
      "basePath": "/",
      "clientCount": 25,
      "configDirty": false,
      "configDirtyAt": 0,
      "cpuPct": 12.5,
      "createdAt": 1700000000,
      "depletedCount": 1,
      "disabledCount": 2,
      "enable": true,
      "guid": "node-guid",
      "hasApiToken": true,
      "id": 1,
      "inboundCount": 3,
      "inboundSyncMode": "all",
      "inboundTags": [
        "in-443-tcp"
      ],
      "lastError": "",
      "lastHeartbeat": 1700000000,
      "latencyMs": 42,
      "memPct": 45.2,
      "name": "edge-1",
      "netDown": 1048576,
      "netUp": 2097152,
      "onlineCount": 5,
      "outboundTag": "direct",
      "panelVersion": "v3.x.x",
      "parentGuid": "",
      "pinnedCertSha256": "",
      "port": 2053,
      "remark": "Primary edge",
      "scheme": "https",
      "status": "online",
      "tlsVerifyMode": "verify",
      "transitive": false,
      "updatedAt": 1700003600,
      "uptimeSecs": 86400,
      "xrayError": "",
      "xrayState": "running",
      "xrayVersion": "25.10.31"
    }
  ]
}
```

--------------------------------

### cURL GET request for HWID status

Source: https://docs.sanaei.dev/docs/reference/api/subscription-server

Sends a GET request to the hwid-status endpoint with bearer token authorization. The response body is a JSON object with active, full, limit, registered, and remaining fields.

```bash
curl -X GET "https://docs.sanaei.dev/stringstring/hwid-status" \
  -H "Authorization: Bearer "
```

--------------------------------

### cURL GET request for subscription links

Source: https://docs.sanaei.dev/docs/reference/api/subscription-server

Sends a GET request to the subscription endpoint to retrieve base64-encoded subscription links. Requires a bearer token in the Authorization header. The response is a JSON object with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/stringstring" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

--------------------------------

### POST /panel/api/server/getNewEchCert

Source: https://docs.sanaei.dev/docs/reference/api/server

Generates a new ECH (Encrypted Client Hello) keypair and config list for the given SNI.

```APIDOC
## POST /panel/api/server/getNewEchCert

### Description
Generates a new ECH (Encrypted Client Hello) keypair and config list for the given SNI.

### Method
POST

### Endpoint
/panel/api/server/getNewEchCert

### Parameters
#### Request Body (application/x-www-form-urlencoded)
- **sni** (string) - Required - Server Name Indication to generate the ECH config for.

### Request Example
```
curl -X POST "https://docs.sanaei.dev/panel/api/server/getNewEchCert" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'sni=string'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success.
- **msg** (string) - Message.
- **obj** (null) - Object.

#### Response Example
```
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

```

--------------------------------

### GET /panel/api/inbounds/list

Source: https://docs.sanaei.dev/docs/reference/api

Lists all inbounds configured on the panel.

```APIDOC
## GET /panel/api/inbounds/list

### Description
Lists all inbounds configured on the panel.

### Method
GET

### Endpoint
/panel/api/inbounds/list

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token or session cookie.

### Request Example
(No request body)

### Response
#### Success Response (200)
- **inbounds** (array) - List of inbound objects.

#### Response Example
{
  "inbounds": []
}
```

--------------------------------

### Restart x-ui after migration

Source: https://docs.sanaei.dev/docs/reference/database

Restart the x-ui service after setting XUI_DB_TYPE and XUI_DB_DSN in /etc/default/x-ui. The source SQLite file is left untouched; remove it manually only after verifying the new backend works.

```bash
systemctl restart x-ui
```