1.11. Work with API

A token is required to work with the API. The token is associated with the account and allows you to manage all services available in it, including delegated.

1. Open the "API" section.
2. On the "Access data" tab, check "I agree with user agreement and terms of service" and click "Activate token":

Token is valid for 6 months:

• If used — since the last time it was used.
• If not used — since its creation.

Limits on the number of API requests:

• Per hour — no more than 3600 requests.
• Per day — no more than 28800 requests.

In response to each request, HTTP headers are added:

• With current limits:
  • X-RateLimit-Hour: 3600 — per hour.
  • X-RateLimit-Day: 28800 — per day.
• With the number of requests that remain before the limits are exhausted:
  • X-RateLimit-Hour-Remaining: XXX — per hour.
  • X-RateLimit-Day-Remaining: XXXX — per day.

The number of requests per second/minute is not limited.

If the limit is exceeded, an error message will be returned with the limit value and the number of seconds remaining until the limit is reset:

• "Too Many Requests per hour. Limit 3600. Pause XXX seconds" — for hourly limit.
• "Too Many Requests per day. Limit 28800. Pause XXXX seconds" — for daily limit.

Also, when the limits are reached, a corresponding notification is sent to email and to the connected messengers (but not more than once a week).

Access restrictions are configured in the "API" section on the "Access restriction" tab:

The working logic is as follows:

• Address list is empty — access is open for everyone.
• There is one or more addresses in the list — access is open only for addresses from the list, for the rest access is closed.

Addresses and subnets in CIDR format are added to the list of allowed addresses using the "Add IP to allowed list" button. All added addresses are displayed in the list below. You can add a note to each of them or remove them from the list.

You can find the list of methods, their descriptions, test their work and get code samples in the "API" section on the "Documentation" tab. The tab consists of several blocks.

The "Methods" block displays a list of available methods:

Block with the name of the selected method contains its detailed description:

• Request sending method — GET or POST.
• URL — address to which the request should be sent.
• Parameters — list of available parameters, data types for each of them and variants of available values.
• Detailed description of the method and its return values (not for all methods).

The left part of the "Request execution" block contains a form for quick sending a request on behalf of the current account, the right part displays the response code and the result of the sent request:

When an action is performed in the control panel, the system automatically captures the data of the last request to the corresponding method and stores it for 10 minutes. During this time, the documentation on the method page will show the date and time of its last call, you can view the list of parameters passed to it and substitute these parameters into the request form. For each method, only the data of the last 1 request made in the current account is stored.

The "Code example" block outputs sample code for using the current method using cURL or the HostingAPI library:

• The current active token is automatically substituted into the string with the parameter $auth_token. If the token is not active, it will have to be activated and substituted into the code manually.
• Parameters from the form are automatically substituted into the string with the parameter $post after the request is executed. If the request was not executed, you will have to specify the parameters yourself.