# 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. Customers 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

Before you can proceed with installing the API Endpoint script, Python needs to be version 3.6 or above.

#### Upgrade Python

- Upgrade Python to 3.6 or higher, see guide [here](https://docs.ultra.cc/books/unofficial-language-installers-3AK/page/install-python-using-pyenv)

With Python updated to version 3.6 or above, you can proceed the installation.

#### Script Installation

- Connect to your Ultra.cc slot 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.usbx.me/util/API-EndPoints/main.sh)
```

- Type `confirm` and press `ENTER` to confirm
- Press `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 Notifiarr.
  - Type the port that you want to use for Notifiarr, 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.

```
Script has been installed successfully.
Creating SQLite3 database and table...
Token successfully generated: <YOUR-AUTH-TOKEN>
 Ultra service API End points to get your service stats:
  ■ Complete Stats........:  https://username.hostname.usbx.me/ultra-api/get_stats
  ■ Storage Stats.........:  https://username.hostname.usbx.me/ultra-api/get_quota
  ■ Traffic Stats.........:  https://username.hostname.usbx.me/ultra-api/get_bandwidth
The script has been installed.
```

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

## Usage

#### Request Script

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.usbx.me/util/API-EndPoints/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:
  - `/get_stats`
  - `/get_quota`
  - `/get_bandwidth`
- 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/get_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.usbx.me/util/API-EndPoints/main.sh)
```

- Type `confirm` and press `ENTER` to confirm
- Press `2` and `ENTER` to proceed the uninstallation
- Press `1` and `ENTER` to confirm
- Done!