# Storage/Traffic API Endpoint

<p class="callout warning">
This is an unofficial script that is provided for your convenience. The script is provided as-is and may not be updated or maintained by Ultra.cc. Clients are welcome to use and customize unofficial scripts for their unique needs and requirements. Unofficial support may be offered via <a href="https://discord.ultra.cc">Discord</a> only and at the sole discretion of Ultra.cc staff. Use at your own risk.
</p>

The Storage/Traffic API Endpoint script will provide three API endpoints to your Ultra.cc service. The script will be installed as a Flask application in `~/scripts/Ultra_API` and run in a screen session called `UltraAPIpoints`. At the moment, three API endpoints are provided, as shown below. 

- Storage usage stats using `quota -s`.
- Traffic stats using `app-traffic info`.
- The above combined into one endpoint.

## Installation

- Connect to your Ultra.cc service via SSH, see guide [here](https://docs.ultra.cc/books/secure-shell-%28ssh%29/page/how-to-connect-to-your-ultracc-slot-via-ssh)
- Once connected, execute the following command:

```sh
bash <(wget -qO- https://scripts.ultra.cc/util-v2/Ultra-API/main.sh)
```

- Type `1` and `ENTER` to proceed with the installation
  - or, if you have already installed the script, and it is not responding. Press `3` and `ENTER` to restart the script.
  - or, if you have already installed the script, and require your authentication token. Press `4` and `ENTER`.
- Next, from the list of your unallocated ports, pick a port to use for the API endpoint script.
  - Type the port that you want to use, press `ENTER` to confirm.
  - To confirm your selection of port, type `confirm` and press `ENTER`.
- After the installation has been successfully completed, the below output should be shown.
  - In your URL's, `username.hostname` will be replaced with the username and hostname of your Ultra.cc service.

```
[INFO] Screen session Ultra-API is running.
[SUCCESS] Ultra service API Endpoints to get your service stats:
  ■ Complete Stats........:  https://username.hostname.usbx.me/ultra-api/total_stats
  ■ Storage Stats.........:  https://username.hostname.usbx.me/ultra-api/get_diskquota
  ■ Traffic Stats.........:  https://username.hostname.usbx.me/ultra-api/get_traffic
```

- The above URL's are where your API endpoints can be accessed.

## Usage

#### Request Script

<p class="callout info">
  The python script below is just an example. It will only work if run from your home directory, not a subdirectory.
</p>

Once you have successfully installed the script, you are ready to start sending request to the API endpoints. Execute the below command to download a basic request script that we offer as a demonstration.

```sh
wget https://scripts.ultra.cc/util-v2/Ultra-API/requester.py
```

- Before you can use the request script you need to amend it and add your username, hostname, and authentication token. Execute the following command to open the script in an editor.

```sh
nano requester.py
```

- At the bottom, you will see the following:

```
url = "https://username.hostname.usbx.me/ultra-api/endpoint"  # Replace with your desired URL
auth_token = "YOUR_AUTH_TOKEN"  # Replace with your actual auth token
```

- In the URL string, replace `username.hostname` with the username and hostname of your Ultra.cc service.
  - Username and hostname can be found on the [UCP](https://cp.ultra.cc). The hostname of your service is the name of the server. For example, in `spica.usbx.me` the hostname is `spica`.
- In the auth_token string, replace `YOUR_AUTH_TOKEN` with the auth token generated during the script installation. By executing the script installation command and selecting option `4`, it will print the auth token again.
- Lastly, you need to amend the last bit of the URL with one of the endpoints printed at script installation. This is done by replacing `/endpoint` with either of the three endpoints provided:
  - `/total-stats`
  - `/get-diskquota`
  - `/get-traffic`
- If done correctly, it should look something like what you see below, but with your specific details:

```
url = "https://coolguy69.spica.usbx.me/ultra-api/total_stats"  # Replace with your desired URL
auth_token = "0JQ3LJOnXq7IiJyujlPFzR9S"  # Replace with your actual auth token
```

- To save your changes and exit the editor, press `ctrl+x` and `y`, then press `ENTER` to confirm.
- Next, run the request script by executing:

```sh
python requester.py
```

- If successful, you should see your stats presented like this:

```
Data from GET request:
{"service_stats_info":{"free_storage_bytes":9664750157824,"free_storage_gb":9001.0,"last_traffic_reset":"2023-08-22T00:00:00","next_traffic_reset":"2023-08-22T00:00:00","total_storage_unit":"G","total_storage_value":11176,"traffic_available_percentage":97.51,"traffic_used_percentage":2.489999999999995,"used_storage_unit":"G","used_storage_value":2175}}
```

#### GET request via curl

- Execute a GET request: 

```sh
curl -X GET -H "Authorization: Bearer YOUR-AUTH-TOKEN" https://username.hostname.usbx.me/ultra-api/endpoint
```

- Make sure to replace `YOUR-AUTH-TOKEN`, `username.hostname`, and `/endpoint`.

## Uninstallation

- Execute the following command:

```sh
bash <(wget -qO- https://scripts.ultra.cc/util-v2/Ultra-API/main.sh)
```

- Press `2` and `ENTER` to proceed the uninstallation
- Done!