Getting started with API

Structure of API request URL

An API request must be sent to https://api.topvisor.com by POST.
A request URL must include the following data:

	<!-- https://api.topvisor.com/{version}/{format}/{operator of action}/{service name}[/{method name}] -->

API Version (v2)
Data format (only JSON supported)
Operator of action
Service name
Method name (optional)
Header: Content-type (optional, "application/json" recommended)
Header: User-Id
Header: Authorization

Example of API request URL:

	<!-- https://api.topvisor.com/{version}/{format}/{operator of action}/{service name}[/{method name}] -->
	https://api.topvisor.com/v2/json/get/user/profile/avatar

Access and authorization

To get started with the Topvisor API, get an API Key.
Authorization request headers:

User-Id:		%USER_ID%
Authorization:	bearer %USER_API_KEY%

Data format in request

The data you send must be UTF-8 encoded.
Data to be passed in two ways: JSON or form-data.

Example of an API request URL that sets a data type:

Content-type: application/json

Content-type: ANY_OTHER // e.g. x-www-form-urlencoded (not recommended)

Response format

Response is encoded UTF-8 encoded.
The only supported response format: JSON.

{"result": /* result */,"nextOffset": /* number (can be absent) */,"total": /* number (can be absent) */,"errors":[/* array of errors (can be absent) */],"messages":[/* array of strings with notes (can be absent) */]}

Find more about nextOffset and total on the Paginated selection page.
Find more about errors on the Errors page.

API limits

You can get up to 10 000 results per request
Up to 5 concurrent requests from a single IP
Up to 5 concurrent requests from a single User-Id

If limits are exceeded, API returns an error with a 429 code.

Data objects

API allows to get, change and remove different data type objects. Each service is applicable to a certain data type. The list of all API services and the related objects is described in the Services section.

For example, the Keyword service allows to manage the following objects: "Keywords", "Groups", and "Folders".

Each data type has a unique list of properties. An example of a data type: Keywords