VPSBG's dev hub
HomePricingKnowledge BaseContact us
HomePricingKnowledge BaseContact us
  1. API Introduction
  • 👋 Hello
  • API Introduction
    • API Introduction
    • How to generate API key?
  • API Reference
    • User
      • 2FA
        • Get 2FA secret key
        • Enable 2FA
        • Disable 2FA
      • Update user
      • Get account information
    • Balance
      • Balance
      • Deposit funds
      • List balance transactions
    • Affiliate
      • Get affiliate information
      • List conversions
      • List payouts
      • Activate affiliate program
      • Update referral code
    • Invoices
      • List invoices
      • Download an invoice
      • Download invoices
    • Support
      • Tickets
        • List tickets
        • List departments
        • List related services
        • Get a ticket
        • Create new ticket
        • Reply to ticket
        • Mark ticket as resolved
        • Download attachment
      • List plans
      • Purchase support plan
      • Renew support plan
      • Cancel support plan
      • Undo cancel request
    • SSH Keys
      • Get an SSH Key
      • Update SSH Key
      • Delete SSH Key
      • List SSH keys
      • Add SSH Key
    • Servers
      • Scale
        • List plans
        • Calculate scale cost
        • Scale a server
      • Addons
        • List available addons
        • Scale addons
        • Calculate scale cost
        • Purchase new addons
        • Cancel addon
        • Undo cancel request
      • Rescue
        • Enable rescue mode
        • Disable rescue mode
      • List plans
      • List servers
      • Server status
      • Get a server
      • Server metrics
      • Bandwidth
      • Deploy new server
      • Start a server
      • Restart a server
      • Stop a server
      • Power off
      • Cancel server
      • Undo cancel request
      • Change password
      • Update hostname
      • Update SSH Keys
      • Modify ISOs
      • Restore
      • Renew server
      • Reinstall Server
      • Change Primary IP
      • Calculate renew amount
    • Plans
      • Plan addon
      • Plan promo-codes
    • Snapshots
      • List snapshots
      • Delete snapshot
    • Backups
      • List backups
      • Delete backup
    • Server Images
      • List server images
    • Floating IPs
      • List Floating IPs
      • Plans
      • Purchase Floating IPs
      • Attach Floating IP
      • Detach Floating IP
      • Cancel Floating IP
      • Delete Floating IP Cancellation
    • IP Addresses
      • Update IP address
    • Network Protection
      • Geo filter
        • Get current geo filter
        • Set geo filter
        • Update geo filter
        • Delete geo filter
      • Whitelist
        • Get status and list of IPs
        • Whitelist IP addresses
        • Update IP addresses list
        • Delete all rules
      • Blacklist
        • Get status and list of IPs
        • Blacklist IP addresses
        • Update IP addresses list
        • Delete all rules
      • General information
      • Bandwidth
      • List blocked IPs
      • List attacks
      • Get an attack
      • Attack bandwidth
    • Orders
      • List orders
      • Get an order
      • Delete order
      • Pay orders
      • Update order
      • Change renewal period
    • ISOs
      • Get an ISO
      • Delete an ISO
      • List ISOs
      • Add ISO
  1. API Introduction

API Introduction

🛠️ Beta Notice#

🚧 This API is currently in Beta version! 🚧
Please note that while this API is in Beta, changes might occur without prior notice. We encourage you to use it cautiously and provide us with your valuable feedback to enhance its functionality and reliability.
Your insights will be highly valuable in improving the API and progressing out of Beta. Thank you for your understanding and cooperation!

🙋‍♂️ Introduction#

The VPSBG API enables users to manage their services and other resources on the VPSBG's platform in a straightforward and programmatic manner, using standard HTTP requests. It uses standard HTTP response codes, verbs, and authentication mechanisms. The API features well-formed and consistent JSON requests and responses, with pagination that simplifies list management.

⚡ Requests#

The API can be accessed by any HTTP client, simply by requesting the appropriate URI. Requests must be sent over HTTPS. The HTTP Method correspondents to the action.
METHODUSAGE
GETTo fetch information about a resource, utilize the GET method, which returns the data in the form of a JSON object. GET methods are solely for read-only purposes and have no effect on any resources.
POSTTo create a new object, send a POST request using the required HTTP method. All necessary attributes should be included in the request body, which must be encoded as JSON.
PATCHSome resources support partial modification with PATCH, which modifies specific attributes without changing the rest.
PUTThe PUT method is used to completely replace an existing resource or create a new one if it doesn't exist. When sending a PUT request, include all attributes necessary for the resource in the request body, encoded as JSON.
DELETETo delete a resource and remove it from both your account and environment, you should utilize the DELETE method. This will delete the specified object if it is present. If the object cannot be found, the operation will return a response indicating that it was not found.

🔢 Response Codes#

The API returns standard HTTP status codes to indicate whether a request was successfull or not. In the table below you can see all HTTP status code that this API might return.
RESPONSEDESCRIPTION
200 OKThe requested information is provided.
201 CreatedResource is created.
202 AcceptedThe resource was updated.
204 No ContentSuccessful request, no response (not needed).
401 UnauthorizedNot authorized (no valid token provided).
403 ForbiddenYou do not have access to this resource.
404 Not FoundNo results founds.
422 Unprocessable ContentValidation error.
423 LockedThe resource is locked at the moment.
429 Too Many RequestsAPI rate limit exceeded.
500 Internal Server ErrorServer-side issue.

✋ Rate limit#

In order to ensure the smooth functioning of the API platform, we have implemented a rate limit per user. Currently, the limit is set at 200 requests per minute. If you exceed this limit, subsequent requests will result in a 429 HTTP error code until the start of the next cycle.
To make it easier for you to manage the rate limit, the following information is included in the response headers of each request:
X-RateLimit-Limit
Indicates the maximum number of requests allowed within a minute.
X-RateLimit-Remaining
Shows the number of remaining requests you have before reaching the rate limit.
Retry-After
If you are already rate limited, this header specifies the time (in seconds) you need to wait before retrying your request.
X-RateLimit-Reset
If you are already rate limited, this header indicates the Unix epoch time when you can send your request again.

🗒️ Pagination and Links#

When pagination is enabled, the response includes a data array, along with links and meta objects that provide pagination details.
By default, 20 items are returned per page. You can customize this by appending ?per_page= to your request URL with the desired number of items (maximum 100). For example: ?per_page=25.

Links Object#

The links object provides URLs for navigating between pages:
first: URL of the first page.
prev: URL of the previous page.
next: URL of the next page.
last: URL of the last page.
If a link isn't applicable (e.g., no previous page on the first page), its value will be null.

Example#

"links": {
    "first": "https://api.vpsbg.eu/v1/servers?page=1",
    "last": "https://api.vpsbg.eu/v1/servers?page=1",
    "prev": null,
    "next": null
}

Meta Object#

The meta object contains additional pagination information:
current_page: Current page number.
from: Starting index of the items returned.
last_page: Total number of pages.
links: Pagination links.
path: Base URL.
per_page: Number of items per page.
to: Ending index of the items returned.
total: Total number of available items.

Example#

"meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://api.vpsbg.eu/v1/servers?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "path": "https://api.vpsbg.eu/v1/servers",
    "per_page": 20,
    "to": 1,
    "total": 1
  }

Controlling Pagination#

Use the following query parameters to control pagination:
page: Specify the page number. Example: ?page=2
per_page: Specify items per page. Example: ?per_page=25

Example Request#

🚩 Permissions#

When generating API tokens, users have the option to select permissions of type: read & write. It is important to note that if an API token is generated with only read permissions, it will only be able to make GET requests. In order to make other types of requests such as POST, PUT, PATCH, or DELETE, the API token must have the ability to write. It is worth mentioning that once an API token is generated with specific permissions, it cannot be changed and needs to be recreated if different permissions are required.
Modified at 2024-10-05 07:15:24
Previous
👋 Hello
Next
How to generate API key?
Built with