# Official API Documentation Understand the basics of the Official HypeProxy.io API and how it works. ## Introduction We are proud to introducting `HypeProxy.io v2.1 API` that bring many improvements :tada: Since the beginning of HypeProxy.io we have provided a pretty poor API, this new release of our platform will change that dramatically. This `v1` API will continue to work through the address: {% content-ref url="/pages/AgnoA2Xtcn1HgVaRBqNy" %} [Getting Started](/basic-concepts/getting-started) {% endcontent-ref %} ## API Swagger With our API we provide a fully-featured swagger that documents all endpoints and allows you to do your tests without setting up a client locally. {% embed url="" %} ![Swagger Screenshot](/files/-MdXGVT9y-93a54cJTRF) # Version Changelog This page describe all of our platform changes. ## HypeProxy.io v2.1 TODO ## **HypeProxy.io v2.0** * **ENHANCED** Global website rebuilt using Microsoft [Blazor](https://docs.microsoft.com/en-US/aspnet/core/blazor/), improving the whole accessibility. * **ENHANCED** Registration, Login, Forgot Password etc. total rebuilt. * **FIXED** Email Notifications: In the paste HypeProxy didn't sent any mails, not even at the register or when a proxy would expire, it's finished! * **FIXED** Billing problems: Invoice only the first month, problems with downloading etc. We have fixed all this problems with a new Invoicing service. * **New** Realtime notifications using SignalR. * **New:** Realtime notifications using SignalR. ## **HypeProxy.io v1.1 -** April 2020 * **New:** Improve responsive of the Landing page. * **New:** Improve Dashboard with a better design and a lot of real time charts. * **New:** Added Real Time Logging feature. * **New:** Added live bandwidth consumption for each proxies. * **New:** Improve the administration center with a lot of new features. * **New:** Added Affiliate Program pills in the sidebar. * **New:** Adding `DataTables` in the Billing & Payments page. * **New:** Added new endpoints for the HypeProxy.io API * **New:** Fix some bugs, enhance UX etc. * **New:** Eliminate Nagle's algorithm delay to speedup small HTTP request to speedup the connexion. ## HypeProxy v1.0 - August 2019 It was our first version of HypeProxy.io, with a minimum number of features (MVP). # Getting Started The `HypeProxy.io` API is organized around a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) architecture, all endpoints need to be [authenticated](/basic-concepts/authentication), and keep in mind that this documentation describes only the `v2` API. Following the REST standard, you will often find a listing endpoint, an endpoint for retrieving a particular item, and sometimes a modification and/or deletion endpoint. ## How to connect to the API? We provide two base URLs, we advise you to use the first one. ```bash curl "https://api.hypeproxy.io/v2/" curl "https://hypeproxy-api.azurewebsites.net/v2/" ``` ## Authentication Our API requires the use of a [JWT token](https://jwt.io/introduction) which can also be passed as a query string parameter. {% content-ref url="/pages/-MdX70aL0b2wZZ\_TzxtX" %} [API Authentication](/basic-concepts/authentication) {% endcontent-ref %} ## Perform a Health Check The API contains a health check endpoint that you can use if you have any impressions of failure. The health check endpoint will also tell you if down bays have been detected. ```bash curl "https://api.hypeproxy.io/health" ``` ## Status Page We have been offering a new status page for a few months now which is accessible [here](https://status.hypeproxy.io/). ![HypeProxy.io Status Page Screenshot.](/files/8l8FSW1IrWGbP2HnPEw8) {% embed url="" %} ### # API Authentication ## How It Works? The HypeProxy.io API requires an authentication token, but we were split between the demand of customers who didn't want to use a complex authentication mechanism like **JWT** and bringing a good level of security to our service, for this reason we decided to propose two mechanisms: 1. [Traditional JWT Authentication](#traditional-jwt-authentication) 2. [Query Parameter Authentication](#query-parameter-authentication) ## Traditional JWT Authentication Here is a classic example of login with a JWT token, using the `Authorization` HTTP header: ```http GET /v2/Profile HTTP/1.1 Host: api.hypeproxy.io Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ``` > The call of the `Profile` endpoint is just an example, it works same on every endpoints. ## Query Parameter Authentication Some people can't make complex requests and/or don't have access to HTTP headers, so we accept the **JWT Token** as query parameter. You just have to pass your JWT token as a `?apikey=` query string. ```bash curl "https://api.hypeproxy.io/v2/Profile?apikey=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" ``` ## API Reference ### Sign In to API To authenticate you need to use the endpoint `/v2/Authentication/SignIn`. ## Login and Get JWT Token. `POST` `https://api.hypeproxy/io/v2/Authentication/SignIn` #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ---------------------------- | | email\* | String | User email | | password\* | String | User password | | otpCode | String | User OTP, if you enabled 2FA | {% tabs %} {% tab title="200: OK Return your JWT Token (valid for 7 days)" %} ```javascript "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" ``` {% endtab %} {% tab title="400: Bad Request User doesn't exists." %} ```javascript { "errors": "This user doesn't exists.", "message": "Request failed.", "statusCode": "BadRequest", "requestDetails": { "userId": "00000000-0000-0000-0000-000000000000", "endpoint": "/v2/Authentication/SignIn", "date": "2021-11-08T12:16:20.6210678Z", "timestamp": 1636373780, "userAgent": "PostmanRuntime/7.28.4", "clientIp": "::1" } } ``` {% endtab %} {% tab title="400: Bad Request Incorrect password." %} ```javascript { "message": "Incorrect password.", "statusCode": "Forbidden", "requestDetails": { "userId": "00000000-0000-0000-0000-000000000000", "endpoint": "/v2/Authentication/SignIn", "date": "2021-11-08T12:18:18.1897927Z", "timestamp": 1636373898, "userAgent": "PostmanRuntime/7.28.4", "clientIp": "::1" } } ``` {% endtab %} {% endtabs %} # Asynchronous Operations Some operations in our API are executed asynchronously, which means that you will not have to wait for the operation to finish. In exchange, you will get a request ID that will allow you to consult the status of the operation via the call of another endpoint. ## Example of Response This is an example of response from an asynchronous operation ([Manual IP Renew](/api/ip-rotation#execute-manual-rotation) in this case). {% embed url="" %} the field `requestId` in the `data` object can be used to retrieve the related operation. {% endembed %} ## Retrieve an Operation with its ID the field `requestId` in the `data` object can be used to retrieve the related operation {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Authentication/SignIn" method="post" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} ## Endpoints Using Asynchronous Operations There is a lit of endpoints using asynchronous operations: * Manual IP Renew * Test # API Rate Limit For obvious security reasons we prevent users to perform too many API requests and in this page we will list the different limitations. The rate limit applies mainly to POST operations, GET endpoints are not limited. ## General Rules ```json [ { "Endpoint": "post:/v2/Authentication/SignUp", "Period": "1m", "Limit": 1 }, { "Endpoint": "post:/v2/Authentication/SignIn", "Period": "1m", "Limit": 5 }, { "Endpoint": "post:/v2/Orders/Validate", "Period": "1s", "Limit": 1 }, { "Endpoint": "post:/v2/Orders/Create", "Period": "15s", "Limit": 1 }, { "Endpoint": "post:/v2/Profile", "Period": "5s", "Limit": 1 }, { "Endpoint": "post:/v2/Tickets", "Period": "1m", "Limit": 1 }, { "Endpoint": "post:/v2/TicketAnswers/*", "Period": "1m", "Limit": 3 }, { "Endpoint": "post:/v2/Credentials/*", "Period": "1m", "Limit": 5 }, { "Endpoint": "post:/v2/Comments/*", "Period": "1m", "Limit": 5 }, { "Endpoint": "get:/v2/Renews/Execute/*", "Period": "30s", "Limit": 1 }, { "Endpoint": "get:/v2/Insight/*", "Period": "30s", "Limit": 1 } ] ``` # IP Rotation / Renewing ## Introduction The IP renew feature is available on some types of proxies like 4G proxies, it's a very useful feature that many of our customers use. {% hint style="success" %} We are constantly improving this feature, we have reduced the renew speed of 4G proxies from more than 8 seconds to less than 5. {% endhint %} We currently support to kinds of IP rotation: * [Automatic](#configure-automatic-rotation): Define an IP rotation every `X` minutes. * [Manual](#execute-manual-rotation): Triggers a rotation at the time of the request. ## Configure Automatic Rotation ### Get the IP Renew Get the renew parameters for a specific [product](/reference/orders-and-purchases/product-details). {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Renews/{productDetailsId}" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} ### Set a IP Renew Delay Define the delay of renew for a specific [product](/reference/orders-and-purchases/product-details), the minimum renew is 1 minute. {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Renews/{productDetailsId}" method="post" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} ### Delete an IP Renew Remove the IP renew feature for a specific [product](/reference/orders-and-purchases/product-details). {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Renews/{productDetailsId}" method="delete" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} ## Execute Manual Rotation The manual renew will be executed as an [asynchronous operation](/basic-concepts/asynchronous-operations), the API will return the related `requestId` of the operation. So don't worry if the request delay is really fast, it's just because it's asynchronous, the renew will be performed in the background and takes about 5 to 8 seconds. {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Renews/Execute/{productDetailsId}" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} # Proxy Insight ## Introduction `Proxy Insight` is one of the core features we are introducing in `HypeProxy.io v2.1` and it allows you to get a lot of information about your proxies and their uses. Keep in mind that if we were to introduce new products that are not just proxies (like a VPN service for example) we will keep the term `Proxy Insight`. All these endpoints require the identifier of your product (called `productDetailsId`). ## API Reference [🔗](/reference/insights) Proxy Insight currently contains 4 endpoints, each rate limited to 1 call every 30 seconds. ### Ping a Proxy {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Insight/Ping/{productDetailsId}" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} ### Get Remote IP Address {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Insight/Ip/{productDetailsId}" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} ### Get IP Detailed Information {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Insight/IpDetails/{productDetailsId}" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} ### Get IP Threats Information {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Insight/IpThreats/{productDetailsId}" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} # Order Process ## Introduction Our payment process is split into two steps, the first step for validation and the second step for order creation, both endpoints use basically same [JSON](https://www.json.org/json-en.html) model. Our order process is divided into two phases, the first consists of validating the order according to a defined model such as a type of product, a desired location, a quantity etc. and the second is the purchasing. Here are the two related endpoints: ``` /v2/Orders/Create /v2/Orders/Validate ``` ## What to Send? Both of endpoints take the same JSON model, containing these properties: * **Product Id**: Which [Product](broken://pages/qUFnJDm0LTOKfWov2Vcz) you want to order. * **Location Id**: In which [Location](broken://pages/UZV0DP2hCk0qBh3C0Iyk) you want to order. * **Payment Method**: Define the payment method to use (Credit Card or Cryptocurrencies) * **Billing Period**: Define the payment term of the order (Like Month, Week or Year) * **Quantity**: How many products do you want to order? * **Is Auto Renewed**: Define if you want to automatically renew your order (subscription) * **\[Optional] Coupon Code** Indicates a discount coupon to be used when ordering. ## Model Example: Here is an example of the JSON model you should send: ```json { "productId": "7d8f2363-2fc9-47af-aae2-c22043af12ed", "locationId": "d6e32771-4733-4de5-9b95-d0ef1b30f00c", "billingPeriod": "Monthly", "paymentMethod": "CreditCard", "quantity": 1, "isAutoRenewed": true } ``` We can deduce from this model an order of this type: * Order of 1 product (4G Proxy) * Located in Nice, France * Paid Monthly * With Credit Card * With a subscription renewed every months # Order Validation Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum ## Validate an order model and return if the order is possible or not. `POST` `https://api.hypeproxy.io/v2/Orders/Validate` #### Request Body | Name | Type | Description | | ----------------------------------------------- | ------- | --------------------------------------------------------- | | productId\* | Guid | Product Id | | locationId\* | Guid | Location Id | | billingPeriod\* | Enum | `Daily`, `Weekly`, `Monthly` or `Yearly` | | paymentMethod\* | Enum | `CreditCard` or `Cryptos` | | quantity\* | Integer | Quantity, like 1, 2, 3, 10 etc | | isAutoRenewed\* | Boolean | If payment should be renewed every end of billing period. | | couponCode | String | If you have a coupon code you can put it there. | {% tabs %} {% tab title="200: OK Validation passed response" %} ```javascript { "message": "Validation Passed. You can now use /v2/Orders endpoint to create an order.", "statusCode": "OK", "requestDetails": { "userId": "00000000-0000-0000-0000-000000000000", "endpoint": "/v2/Orders/Validate", "date": "2021-11-07T15:01:06.776251Z", "timestamp": 1636297266, "userAgent": "PostmanRuntime/7.28.4", "clientIp": "::1" }, "data": { "price": { "unitPrice": 55, "totalPrice": 55 } } } ``` {% endtab %} {% tab title="400: Bad Request Insufficient quantity available for this kind of products/locations." %} ```javascript { "errors": [ { "code": "InsufficientQuantityAvailable", "message": "Insufficient quantity available for this kind of products/locations." } ], "message": "Request failed.", "statusCode": "BadRequest", "requestDetails": { "userId": "00000000-0000-0000-0000-000000000000", "endpoint": "/v2/Orders/Validate", "date": "2021-11-07T15:02:02.753931Z", "timestamp": 1636297322, "userAgent": "PostmanRuntime/7.28.4", "clientIp": "::1" } } ``` {% endtab %} {% tab title="400: Bad Request Payment autorenew not possible with this payment method." %} ```javascript { "errors": [ { "code": "UnavailableAutomaticRenew", "message": "With this payment method it's not possible to enable autorenew." } ], "message": "Request failed.", "statusCode": "BadRequest", "requestDetails": { "userId": "00000000-0000-0000-0000-000000000000", "endpoint": "/v2/Orders/Validate", "date": "2021-11-07T15:04:15.939415Z", "timestamp": 1636297455, "userAgent": "PostmanRuntime/7.28.4", "clientIp": "::1" } } ``` {% endtab %} {% endtabs %} # Order Creation # V1 API Documentation ## Introduction {% hint style="danger" %} When we'll migrate to HypeProxy.io v2.1 this API will no longer be operational. {% endhint %} `HypeProxy.io v1 API` offers a JWT authentication, it's however possible to [renew the IP](#renew-ip) only with its proxy ID. If you need more help with the API v1 please feel free to join our [live chat](https://go.crisp.chat/chat/embed/?website_id=c96435ae-a92e-469f-b556-6befad2ff1d8). ## Retrieve your Proxy ID First of all you have to connect to your dashboard, go to the section [4G / LTE Proxies](https://hypeproxy.io/dashboard/products/4g-proxies), then in the proxies list, you can see your IDs it's the sequence of alphanumeric characters with hash. So for use the API you have to send the ID, following the screenshot below it's `00000000`. ![Dashboard Screenshot.](/files/5FT8bN1dE57VrDULzBeP) ## API Reference ### Renew IP ## Renew the IP of a specific proxy \[No Auth Required] `GET` `https://hypeproxy.io/api/Utils/DirectRenewIp/{id}` This endpoint trigger the IP renew of the related proxy as an asynchronous operation, the process take around 8 seconds in background to be proceed and requires the reboot of the USB modem. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ---- | ------------------------------------------ | | id\* | | Proxy ID, here to know how to get this ID. | {% tabs %} {% tab title="200: OK IP Renew Response." %} ```javascript "IP Renew done." ``` Keep in mind that the operation is asynchronous, if the renew fail the api will always return the same response. {% endtab %} {% endtabs %} # \[Generic] Products Products endpoints, it's all the differents kind of products we provide. {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Products" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} {% openapi src="/files/gs4oEIFDowGgQW6W05CO" path="/v2/Products/{productId}" method="get" %} [swagger.json](https://3875752105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MdX5lpI2Fre91A5ipOw%2Fuploads%2FkaenjPxy480P6u3WD1PU%2Fswagger.json?alt=media\&token=d65d1f23-7d90-4149-af11-e3b4c609807e) {% endopenapi %} # \[Generic] Bays Bays endpoints, get information about ou Bays. # \[Generic] Locations Locations of our Bays. # \[Generic] Coupons # \[Generic] News News endpoint, get the latest HypeProxy.io news. # Billing # Invoices Invoices endpoints # Orders & Purchases # Orders # Purchases A `Purchase` is related to one order, can contain many products (`Content` field) {% embed url="" %} # Product Details # Credentials # Support # Tickets Tickets endpoints. # Ticket Answers Ticket answers endpoints. # Profile Profile endpoints, get and update your profile. # Insights # Renews # Command Line Interface (CLI) Our new API permits the use of our first command line tool: `hproxy-ctl`. ## Take a Look ``` ██╗ ██╗██╗ ██╗██████╗ ███████╗██████╗ ██████╗ ██████╗ ██╗ ██╗██╗ ██╗ ██║ ██║╚██╗ ██╔╝██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔═══██╗╚██╗██╔╝╚██╗ ██╔╝ ███████║ ╚████╔╝ ██████╔╝█████╗ ██████╔╝██████╔╝██║ ██║ ╚███╔╝ ╚████╔╝ ██╔══██║ ╚██╔╝ ██╔═══╝ ██╔══╝ ██╔═══╝ ██╔══██╗██║ ██║ ██╔██╗ ╚██╔╝ ██║ ██║ ██║ ██║ ███████╗██║ ██║ ██║╚██████╔╝██╔╝ ██╗ ██║ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ Use HypeProxy.io API with command line. Written in Rust. https://github.com/hypeproxy/hpro-ctl FLAGS: -h, --help Prints help information --no-banner Disable showing the banner on start -V, --version Prints version information OPTIONS: -c, --config Specify the configuration file ``` ## Download & Install