### Get Keywords List - Bash

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Fetches a list of all keywords within a project, supporting filtering by groups, folders, and tags. Requires a project ID and API token for authentication.

```bash
curl -X POST "https://api.topvisor.com/get/keywords_2/keywords/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "project_id": 12345,
    "limit": 500,
    "offset": 0,
    "fields": ["id", "name", "group_id", "target", "tags"],
    "group_folder_id_depth": true,
    "show_trash": false
  }'
```

--------------------------------

### Get Projects List - Bash

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves a list of all user SEO projects with options for filtering, sorting, and pagination. It can also fetch additional information about search engines and regions. Requires an API token for authentication.

```bash
curl -X POST "https://api.topvisor.com/get/projects_2/projects/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "limit": 100,
    "offset": 0,
    "fields": ["id", "name", "url", "on", "tags"],
    "show_searchers_and_regions": 1
  }'
```

--------------------------------

### GET /get/keywords_2/keywords/

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves a list of keywords for a specific project. Supports filtering by groups, folders, and tags.

```APIDOC
## GET /get/keywords_2/keywords/

### Description
Retrieves a list of keywords for a specific project. Supports filtering by groups, folders, and tags.

### Method
POST

### Endpoint
/get/keywords_2/keywords/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **project_id** (integer) - Required - The ID of the project to retrieve keywords from.
- **limit** (integer) - Optional - The maximum number of keywords to return.
- **offset** (integer) - Optional - The number of keywords to skip.
- **fields** (array of strings) - Optional - Specifies which fields to include in the response. Example: `["id", "name", "group_id", "target", "tags"]
- **group_folder_id_depth** (boolean) - Optional - If true, includes group and folder IDs in a nested structure.
- **show_trash** (boolean) - Optional - If true, includes keywords from the trash.

### Request Example
```json
{
  "project_id": 12345,
  "limit": 500,
  "offset": 0,
  "fields": ["id", "name", "group_id", "target", "tags"],
  "group_folder_id_depth": true,
  "show_trash": false
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of keyword objects.
  - **id** (integer) - The unique identifier of the keyword.
  - **name** (string) - The keyword phrase.
  - **group_id** (integer) - The ID of the group the keyword belongs to.
  - **target** (string or null) - The target URL associated with the keyword.
  - **tags** (array of integers) - An array of tag IDs associated with the keyword.
- **total** (integer) - The total number of keywords available.
- **nextOffset** (integer or null) - The offset for the next page of results.
- **errors** (null) - Should be null on success.

#### Response Example
```json
{
  "result": [
    {
      "id": 111,
      "name": "купить телефон",
      "group_id": 5,
      "target": "https://mysite.ru/phones/",
      "tags": [1]
    },
    {
      "id": 112,
      "name": "смартфоны цена",
      "group_id": 5,
      "target": null,
      "tags": []
    }
  ],
  "total": 1500,
  "nextOffset": 500,
  "errors": null
}
```
```

--------------------------------

### GET /get/projects_2/projects/

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves a list of all user SEO projects. Supports filtering, sorting, and pagination, along with options to include search engine and region information.

```APIDOC
## GET /get/projects_2/projects/

### Description
Retrieves a list of all user SEO projects. Supports filtering, sorting, and pagination, along with options to include search engine and region information.

### Method
POST

### Endpoint
/get/projects_2/projects/

### Parameters
#### Query Parameters
None

#### Request Body
- **limit** (integer) - Optional - The maximum number of projects to return.
- **offset** (integer) - Optional - The number of projects to skip before starting to collect the result set.
- **fields** (array of strings) - Optional - Specifies which fields to include in the response. Example: `["id", "name", "url", "on", "tags"]
- **show_searchers_and_regions** (integer) - Optional - If set to 1, includes searcher and region data in the response.

### Request Example
```json
{
  "limit": 100,
  "offset": 0,
  "fields": ["id", "name", "url", "on", "tags"],
  "show_searchers_and_regions": 1
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of project objects.
  - **id** (integer) - The unique identifier of the project.
  - **name** (string) - The name of the project.
  - **url** (string) - The URL of the project.
  - **on** (integer) - Indicates if the project is active (1) or inactive (0).
  - **tags** (array of integers) - An array of tag IDs associated with the project.
  - **searchers** (array) - Optional. Information about search engines.
  - **regions** (array) - Optional. Information about regions.
- **total** (integer) - The total number of projects available.
- **nextOffset** (integer or null) - The offset for the next page of results, or null if there are no more results.
- **errors** (null) - Should be null on success.

#### Response Example
```json
{
  "result": [
    {
      "id": 12345,
      "name": "example.com",
      "url": "https://example.com",
      "on": 1,
      "tags": [1],
      "searchers": [...],
      "regions": [...] 
    }
  ],
  "total": 15,
  "nextOffset": null,
  "errors": null
}
```
```

--------------------------------

### Get Competitor Report (Bash)

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Fetches competitor analysis data based on keywords or URLs, grouped by domains. Requires parameters like query, type, date, and intersection. Returns a list of competitor domains with metrics or errors.

```bash
# Получить отчёт по конкурентам
curl -X POST "https://api.topvisor.com/get/competitors_2/table/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "by_type": "keywords",
    "region_index": 1,
    "query": "купить телефон",
    "type": "organic",
    "view": "default",
    "date": "2024-01-20",
    "intersection": 0.5,
    "limit": 50
  }'

# Ожидаемый ответ:
# {
#   "result": [
#     {
#       "domain": "competitor1.ru",
#       "visibility": 78.5,
#       "avg_position": 12.3,
#       "keywords_count": 245
#     }
#   ],
#   "total": 150,
#   "errors": null
# }
```

--------------------------------

### Get Balance Information (Bash)

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves account balance information, including total, personal, and bonus balances, as well as the current tariff. Requires specifying the desired fields. Returns balance details or errors.

```bash
# Получить информацию о балансе
curl -X POST "https://api.topvisor.com/get/bank_2/info/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "fields": ["balance_all", "balance_personal", "balance_bonus", "tariff"]
  }'

# Ожидаемый ответ:
# {
#   "result": {
#     "balance_all": 15000.50,
#     "balance_personal": 12000.00,
#     "balance_bonus": 3000.50,
#     "tariff": "Pro"
#   },
#   "errors": null
# }
```

--------------------------------

### Get SERP Snapshot History (Bash)

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves the history of search engine results page (SERP) snapshots, including competitor position analysis over dates. Requires project ID, region, date range, and fields to display. Returns competitor data and date information or errors.

```bash
# Получить историю снимков выдачи
curl -X POST "https://api.topvisor.com/get/snapshots_2/history/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "project_id": 12345,
    "region_index": 1,
    "date1": "2024-01-01",
    "date2": "2024-01-31",
    "type_range": 3,
    "count_dates": 31,
    "show_exists_dates": true,
    "show_ams": true,
    "positions_fields": ["position", "url"],
    "limit": 100
  }'

# Ожидаемый ответ:
# {
#   "result": {
#     "competitors": [
#       {
#         "domain": "competitor.ru",
#         "protocol": "https",
#         "summariesData": {
#           "2024-01-15": {
#             "countUrls": 45,
#             "avg": 15.2,
#             "median": 12.0,
#             "tops": {"1_10": 8, "11_20": 15, "all": 45}
#           }
#         }
#       }
#     ],
#     "dates": ["2024-01-15", "2024-01-20"],
#     "depthPositions": 100,
#     "countKeywords": 500,
#     "existsDates": ["2024-01-15", "2024-01-20"]
#   },
#   "errors": null
# }
```

--------------------------------

### Get Competitors Report

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves a report analyzing competitors based on keywords or URLs, with grouping by domain.

```APIDOC
## POST /get/competitors_2/table/

### Description
Retrieves data analyzing competitors by keywords or URL, grouped by domain.

### Method
POST

### Endpoint
https://api.topvisor.com/get/competitors_2/table/

### Parameters
#### Request Body
- **by_type** (string) - Required - Specifies the analysis type, e.g., "keywords" or "domain".
- **region_index** (integer) - Required - The index of the region for analysis.
- **query** (string) - Optional - The search query to analyze competitors for.
- **type** (string) - Required - The type of data to retrieve (e.g., "organic").
- **view** (string) - Optional - The view format for the results (e.g., "default").
- **date** (string) - Optional - The date for the analysis in YYYY-MM-DD format.
- **intersection** (float) - Optional - The intersection threshold for competitor analysis.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "by_type": "keywords",
  "region_index": 1,
  "query": "купить телефон",
  "type": "organic",
  "view": "default",
  "date": "2024-01-20",
  "intersection": 0.5,
  "limit": 50
}
```

### Response
#### Success Response (200)
- **result** (array of objects) - An array containing competitor data.
  - **domain** (string) - The domain of the competitor.
  - **visibility** (float) - The visibility score of the competitor.
  - **avg_position** (float) - The average position of the competitor's keywords.
  - **keywords_count** (integer) - The number of keywords the competitor ranks for.
- **total** (integer) - The total number of competitors found.
- **errors** (null) - Contains any errors encountered.

#### Response Example
```json
{
  "result": [
    {
      "domain": "competitor1.ru",
      "visibility": 78.5,
      "avg_position": 12.3,
      "keywords_count": 245
    }
  ],
  "total": 150,
  "errors": null
}
```
```

--------------------------------

### Get Balance Information

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves information about the user's account balance, including total, personal, and bonus balances, as well as the current tariff.

```APIDOC
## POST /get/bank_2/info/

### Description
Retrieves information about the account balance and the user's current tariff.

### Method
POST

### Endpoint
https://api.topvisor.com/get/bank_2/info/

### Parameters
#### Request Body
- **fields** (array of strings) - Required - Specifies the balance fields to retrieve (e.g., ["balance_all", "balance_personal", "balance_bonus", "tariff"]).

### Request Example
```json
{
  "fields": ["balance_all", "balance_personal", "balance_bonus", "tariff"]
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the balance information.
  - **balance_all** (float) - The total balance.
  - **balance_personal** (float) - The personal balance.
  - **balance_bonus** (float) - The bonus balance.
  - **tariff** (string) - The name of the current tariff.

#### Response Example
```json
{
  "result": {
    "balance_all": 15000.50,
    "balance_personal": 12000.00,
    "balance_bonus": 3000.50,
    "tariff": "Pro"
  }
}
```
```

--------------------------------

### Get SERP Snapshots History

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves the history of search engine results page (SERP) snapshots, including competitor position analysis over dates.

```APIDOC
## POST /get/snapshots_2/history/

### Description
Retrieves the history of search engine results page (SERP) snapshots, analyzing competitor positions over specified dates.

### Method
POST

### Endpoint
https://api.topvisor.com/get/snapshots_2/history/

### Parameters
#### Request Body
- **project_id** (integer) - Required - The ID of the project.
- **region_index** (integer) - Required - The index of the region for which to retrieve snapshots.
- **date1** (string) - Required - The start date for the history (YYYY-MM-DD).
- **date2** (string) - Required - The end date for the history (YYYY-MM-DD).
- **type_range** (integer) - Optional - The type of range for analysis.
- **count_dates** (integer) - Optional - The number of dates to count.
- **show_exists_dates** (boolean) - Optional - Whether to show only dates with existing snapshots.
- **show_ams** (boolean) - Optional - Whether to show AMS data.
- **positions_fields** (array of strings) - Optional - Fields to include for position data (e.g., ["position", "url"]).
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "project_id": 12345,
  "region_index": 1,
  "date1": "2024-01-01",
  "date2": "2024-01-31",
  "type_range": 3,
  "count_dates": 31,
  "show_exists_dates": true,
  "show_ams": true,
  "positions_fields": ["position", "url"],
  "limit": 100
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the SERP snapshot history data.
  - **competitors** (array of objects) - Data for each competitor.
    - **domain** (string) - The competitor's domain.
    - **protocol** (string) - The protocol used by the competitor (e.g., "https").
    - **summariesData** (object) - Summary data for specific dates.
      - **YYYY-MM-DD** (object) - Data for a specific date.
        - **countUrls** (integer) - Number of URLs found.
        - **avg** (float) - Average position.
        - **median** (float) - Median position.
        - **tops** (object) - Distribution of positions in top ranges (e.g., "1_10", "11_20").
  - **dates** (array of strings) - List of dates for which snapshots are available.
  - **depthPositions** (integer) - The depth of position tracking.
  - **countKeywords** (integer) - The total count of keywords analyzed.
  - **existsDates** (array of strings) - Dates for which snapshots actually exist.
- **errors** (null) - Contains any errors encountered.

#### Response Example
```json
{
  "result": {
    "competitors": [
      {
        "domain": "competitor.ru",
        "protocol": "https",
        "summariesData": {
          "2024-01-15": {
            "countUrls": 45,
            "avg": 15.2,
            "median": 12.0,
            "tops": {"1_10": 8, "11_20": 15, "all": 45}
          }
        }
      }
    ],
    "dates": ["2024-01-15", "2024-01-20"],
    "depthPositions": 100,
    "countKeywords": 500,
    "existsDates": ["2024-01-15", "2024-01-20"]
  },
  "errors": null
}
```
```

--------------------------------

### Get Site Audit Summary (Bash)

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves a summary of technical audit results for a website, categorized by errors and warnings. Requires project ID and check ID. Returns a list of categories with counts or errors.

```bash
# Получить сводку аудита
curl -X POST "https://api.topvisor.com/get/audit_2/audit/summary/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "project_id": 12345,
    "check_id": 67890,
    "filter_check_type": ["error", "warning"],
    "filter_check_state": null,
    "limit": 100
  }'

# Ожидаемый ответ:
# {
#   "result": [
#     {
#       "category": "pages",
#       "subcategory": "indexing",
#       "count_checks_success": 45,
#       "count_checks_warning": 12,
#       "count_checks_error": 3
#     }
#   ],
#   "errors": null
# }
```

--------------------------------

### Get Site Audit Summary

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves a summary of technical audit results for a website, categorized by errors and warnings.

```APIDOC
## POST /get/audit_2/audit/summary/

### Description
Retrieves a summary of technical audit results for a website, categorized by errors and warnings.

### Method
POST

### Endpoint
https://api.topvisor.com/get/audit_2/audit/summary/

### Parameters
#### Request Body
- **project_id** (integer) - Required - The ID of the project.
- **check_id** (integer) - Required - The ID of the audit check.
- **filter_check_type** (array of strings) - Optional - Filters results by check type (e.g., ["error", "warning"]).
- **filter_check_state** (null) - Optional - Filters results by check state.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "project_id": 12345,
  "check_id": 67890,
  "filter_check_type": ["error", "warning"],
  "filter_check_state": null,
  "limit": 100
}
```

### Response
#### Success Response (200)
- **result** (array of objects) - An array containing audit summary data per category.
  - **category** (string) - The category of the audit check (e.g., "pages").
  - **subcategory** (string) - The subcategory of the audit check (e.g., "indexing").
  - **count_checks_success** (integer) - The number of successful checks in this category.
  - **count_checks_warning** (integer) - The number of warning checks in this category.
  - **count_checks_error** (integer) - The number of error checks in this category.
- **errors** (null) - Contains any errors encountered.

#### Response Example
```json
{
  "result": [
    {
      "category": "pages",
      "subcategory": "indexing",
      "count_checks_success": 45,
      "count_checks_warning": 12,
      "count_checks_error": 3
    }
  ],
  "errors": null
}
```
```

--------------------------------

### Get User Data - Bash

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves data for the currently authenticated user using the /get/users_2/ endpoint. Requires an API token for authorization. The request body is empty, and the response contains user details like ID, email, name, language, and timezone.

```bash
# Получить данные пользователя
curl -X POST "https://api.topvisor.com/get/users_2/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{}'

# Ожидаемый ответ:
# {
#   "result": {
#     "id": 12345,
#     "email": "user@example.com",
#     "name": "Иван Иванов",
#     "lang": "ru",
#     "timezone": "Europe/Moscow"
#   },
#   "errors": null
# }
```

--------------------------------

### GET /get/positions_2/history/

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves the historical position data for keywords in search engines over a specified period. Supports filtering by dynamic changes.

```APIDOC
## GET /get/positions_2/history/

### Description
Retrieves the historical position data for keywords in search engines over a specified period. Supports filtering by dynamic changes.

### Method
POST

### Endpoint
/get/positions_2/history/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **project_id** (integer) - Required - The ID of the project.
- **regions_indexes** (array of integers) - Required - An array of region IDs for which to retrieve data.
- **date1** (string) - Required - The start date for the history (YYYY-MM-DD).
- **date2** (string) - Required - The end date for the history (YYYY-MM-DD).
- **type_range** (integer) - Required - Type of range for position data (e.g., 2 for daily).
- **count_dates** (integer) - Required - The number of dates to count within the range.
- **positions_fields** (array of strings) - Optional - Specifies which position-related fields to include. Example: `["position", "snippet_url"]
- **show_headers** (boolean) - Optional - If true, includes header information in the response.
- **show_exists_dates** (boolean) - Optional - If true, indicates which dates have data.
- **show_top_by_depth** (integer) - Optional - Filters results by top N positions.
- **filter_by_dynamic** (null or other types) - Optional - Filters results based on dynamic changes (value depends on specific filtering needs).
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "project_id": 12345,
  "regions_indexes": [1, 2],
  "date1": "2024-01-01",
  "date2": "2024-01-31",
  "type_range": 2,
  "count_dates": 31,
  "positions_fields": ["position", "snippet_url"],
  "show_headers": true,
  "show_exists_dates": true,
  "show_top_by_depth": 100,
  "filter_by_dynamic": null,
  "limit": 100
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of keyword position history objects.
  - **id** (integer) - The keyword ID.
  - **name** (string) - The keyword phrase.
  - **positionsData** (object) - An object containing position data for each date.
    - **date** (object) - Contains position details for a specific date.
      - **position** (integer) - The search engine position.
      - **snippet_url** (string or null) - The URL shown in the search snippet.
      - ... other fields specified in `positions_fields`
- **errors** (null) - Should be null on success.

#### Response Example
```json
{
  "result": [
    {
      "id": 111,
      "name": "купить телефон",
      "positionsData": {
        "1": { 
          "position": 5,
          "snippet_url": "https://example.com/phone"
        }
      }
    }
  ],
  "errors": null
}
```
```

--------------------------------

### Get Positions History - Bash

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves the historical positions of keywords in search engines for a specified period, with options to filter by dynamic changes. Requires project ID, date range, and API token.

```bash
curl -X POST "https://api.topvisor.com/get/positions_2/history/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "project_id": 12345,
    "regions_indexes": [1, 2],
    "date1": "2024-01-01",
    "date2": "2024-01-31",
    "type_range": 2,
    "count_dates": 31,
    "positions_fields": ["position", "snippet_url"],
    "show_headers": true,
    "show_exists_dates": true,
    "show_top_by_depth": 100,
    "filter_by_dynamic": null,
    "limit": 100
  }'
```

--------------------------------

### TypeScript API Method Path and Service Name Extraction

Source: https://github.com/topvisor/topvisor-openapi/blob/main/README.md

This TypeScript code snippet demonstrates how to extract service names and method paths from OpenAPI schema definitions. It leverages utility types to infer types for API paths and service names, providing autocompletion and type checking within an IDE. This requires the 'topvisor-openapi' package to be installed.

```typescript
import type { paths } from 'topvisor-openapi/src/ts/Topvisor.ts';

type ExtractServicesNamesFromPaths<T> = T extends `/${string}/${infer P}/${string}` ? P : never

/**
 * Имя сервиса
 */
type ServicesNames = ExtractServicesNamesFromPaths<Path>;

/**
 * Путь к вызову метрода
 */
type Path = keyof paths;

const methodPath: Path = '/get/payments_2/'; // <-- В ходе написания кода вы будете получать подсказки
const serviceName: ServicesNames = 'example_2';
```

--------------------------------

### Create New Project - Bash

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Creates a new SEO project for website tracking. The URL of the domain or page is a mandatory parameter. Authentication with an API token is required.

```bash
curl -X POST "https://api.topvisor.com/add/projects_2/projects/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "url": "https://mysite.ru",
    "name": "Мой сайт",
    "tags": [1, 2],
    "folder_id": null,
    "on": 1
  }'
```

--------------------------------

### POST /add/projects_2/projects/

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Creates a new project for website position tracking. Requires at least the domain or page URL.

```APIDOC
## POST /add/projects_2/projects/

### Description
Creates a new project for website position tracking. Requires at least the domain or page URL.

### Method
POST

### Endpoint
/add/projects_2/projects/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL of the domain or page to track.
- **name** (string) - Optional - The name of the project.
- **tags** (array of integers) - Optional - An array of tag IDs to associate with the project.
- **folder_id** (integer or null) - Optional - The ID of the folder to place the project in.
- **on** (integer) - Optional - Set to 1 to activate the project immediately, 0 otherwise.

### Request Example
```json
{
  "url": "https://mysite.ru",
  "name": "Мой сайт",
  "tags": [1, 2],
  "folder_id": null,
  "on": 1
}
```

### Response
#### Success Response (200)
- **result** (integer) - The ID of the newly created project.
- **errors** (null) - Should be null on success.
- **messages** (array of strings) - An array of messages, e.g., confirmation of creation.

#### Response Example
```json
{
  "result": 67890,
  "errors": null,
  "messages": ["Проект успешно создан"]
}
```
```

--------------------------------

### Manage Project Notes - Bash

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Provides methods for managing project notes, including adding, editing, retrieving, and deleting. The /add/annotations_2/ endpoint creates a new note with project ID, date, text, and service. The /get/annotations_2/ endpoint retrieves notes for a specific project, supporting pagination with limit and offset.

```bash
# Добавить примечание
curl -X POST "https://api.topvisor.com/add/annotations_2/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{ "project_id": 12345, "date": "2024-01-15", "text": "Обновление алгоритма Google", "service": "positions" }'

# Получить примечания проекта
curl -X POST "https://api.topvisor.com/get/annotations_2/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{ "project_id": 12345, "limit": 50, "offset": 0 }'

# Ожидаемый ответ для GET:
# {
#   "result": [
#     {
#       "id": 999,
#       "project_id": 12345,
#       "date": "2024-01-15",
#       "text": "Обновление алгоритма Google",
#       "service": "positions"
#     }
#   ],
#   "total": 25,
#   "errors": null
# }
```

--------------------------------

### Add Searcher to Project (Bash)

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Adds a search engine to a project for position tracking. Requires project ID and a searcher key. Returns a success message or errors.

```bash
# Добавить Яндекс к проекту
curl -X POST "https://api.topvisor.com/add/positions_2/searchers/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "project_id": 12345,
    "searcher_key": 0
  }'

# searcher_key: 0 - Яндекс, 1 - Google, 3 - Mail.ru, и т.д.
# Ожидаемый ответ:
# {
#   "result": null,
#   "errors": null,
#   "messages": ["Поисковая система добавлена"]
# }
```

--------------------------------

### Pagination

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Learn how to implement pagination for list-based API responses.

```APIDOC
## Pagination

### Description
Methods that return lists of items support pagination using the `limit` and `offset` query parameters. The response includes `total` (total number of items) and `nextOffset` (offset for the next page).

### Parameters
- **limit** (integer) - Optional - Specifies the maximum number of items to return per page. Defaults to 50.
- **offset** (integer) - Optional - Specifies the number of items to skip from the beginning of the list. Used for pagination.

### Response Fields
- **total** (integer) - The total count of items available for the request.
- **nextOffset** (integer) - The offset value to use for fetching the next page of results. If `null`, there are no more pages.

### Example Usage (Conceptual)
To get the first page of results:
```bash
# Example request with limit and offset
curl -X POST "https://api.topvisor.com/some/list/endpoint/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{ 
    "limit": 10, 
    "offset": 0 
  }'
```

To get the second page of results (assuming `nextOffset` from the first response was 10):
```bash
# Example request for the next page
curl -X POST "https://api.topvisor.com/some/list/endpoint/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{ 
    "limit": 10, 
    "offset": 10 
  }'
```
```

--------------------------------

### Retrieve Keywords (First Page) - cURL

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

This snippet demonstrates how to fetch the first page of keyword data from the Topvisor API using cURL. It specifies the project ID, limit, and offset for the request. The response includes the results, total count, and the next offset for pagination.

```shell
curl -X POST "https://api.topvisor.com/get/keywords_2/keywords/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "project_id": 12345,
    "limit": 100,
    "offset": 0
  }'
```

--------------------------------

### Create Support Ticket - Bash

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Creates a new support ticket using the /add/tickets_2/tickets/ endpoint. Requires the ticket text, type, language, resource URL, and optional tags. The response includes the new ticket ID and confirmation messages.

```bash
# Создать тикет в поддержку
curl -X POST "https://api.topvisor.com/add/tickets_2/tickets/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{ "text": "Не обновляются позиции проекта 12345", "type": "system", "lang": "ru", "resource": "https://topvisor.com/ru/projects/12345/", "tags": [1] }'

# Ожидаемый ответ:
# {
#   "result": 54321,
#   "errors": null,
#   "messages": ["Тикет #54321 создан"]
# }
```

--------------------------------

### POST /get/keywords_2/keywords/

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Retrieves a paginated list of keywords for a given project. This endpoint allows fetching keyword data in batches, essential for handling large datasets.

```APIDOC
## POST /get/keywords_2/keywords/

### Description
Retrieves a paginated list of keywords for a given project. This endpoint allows fetching keyword data in batches, essential for handling large datasets.

### Method
POST

### Endpoint
https://api.topvisor.com/get/keywords_2/keywords/

### Parameters
#### Request Body
- **project_id** (integer) - Required - The ID of the project to retrieve keywords from.
- **limit** (integer) - Optional - The maximum number of keywords to return per page. Defaults to 100.
- **offset** (integer) - Optional - The number of keywords to skip before starting to collect the result set. Defaults to 0.

### Request Example
```json
{
  "project_id": 12345,
  "limit": 100,
  "offset": 0
}
```

### Response
#### Success Response (200)
- **result** (array) - A list of keyword objects.
- **total** (integer) - The total number of keywords available for the project.
- **nextOffset** (integer | null) - The offset for the next page of results, or null if this is the last page.
- **errors** (null) - Placeholder for potential errors, expected to be null on success.

#### Response Example
```json
{
  "result": [
    // ... keyword objects ...
  ],
  "total": 5000,
  "nextOffset": 100,
  "errors": null
}
```
```

--------------------------------

### POST /add/keywords_2/keywords/

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Adds a new keyword to a specified project group. Supports automatic duplicate handling.

```APIDOC
## POST /add/keywords_2/keywords/

### Description
Adds a new keyword to a specified project group. Supports automatic duplicate handling.

### Method
POST

### Endpoint
/add/keywords_2/keywords/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **project_id** (integer) - Required - The ID of the project to add the keyword to.
- **name** (string) - Required - The keyword phrase to add.
- **to_id** (integer) - Required - The ID of the group to add the keyword to.
- **to_type** (string) - Required - Specifies the type of destination, e.g., `"in_group"`.
- **tags** (array of integers) - Optional - An array of tag IDs to associate with the keyword.
- **target** (string) - Optional - The target URL for the keyword.
- **move_duplicate** (boolean) - Optional - If true, moves duplicate keywords.
- **move_duplicate_group_name** (string) - Optional - The name of the group to move duplicates to if `move_duplicate` is true.

### Request Example
```json
{
  "project_id": 12345,
  "name": "купить ноутбук недорого",
  "to_id": 5,
  "to_type": "in_group",
  "tags": [1, 3],
  "target": "https://mysite.ru/laptops/",
  "move_duplicate": true,
  "move_duplicate_group_name": "Дубликаты"
}
```

### Response
#### Success Response (200)
- **result** (array of objects) - An array containing information about the added keyword(s).
  - **id** (integer) - The ID of the added keyword.
  - **name** (string) - The name of the added keyword.
- **errors** (null) - Should be null on success.

#### Response Example
```json
{
  "result": [{"id": 999, "name": "купить ноутбук недорого"}],
  "errors": null
}
```
```

--------------------------------

### Project Notes API

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Manage project notes, including adding, editing, retrieving, and deleting.

```APIDOC
## Project Notes API

### Description
This API allows for the management of project notes. You can add, edit, retrieve, and delete notes associated with specific projects.

### Endpoints
- `/add/annotations_2/`
- `/edit/annotations_2/`
- `/get/annotations_2/`
- `/del/annotations_2/`

### Add Note
#### Method
POST

#### Endpoint
https://api.topvisor.com/add/annotations_2/

#### Parameters
##### Request Body
- **project_id** (integer) - Required - The ID of the project to which the note belongs.
- **date** (string) - Required - The date of the note (YYYY-MM-DD).
- **text** (string) - Required - The content of the note.
- **service** (string) - Required - The service associated with the note (e.g., "positions").

#### Request Example
```bash
curl -X POST "https://api.topvisor.com/add/annotations_2/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{ 
    "project_id": 12345, 
    "date": "2024-01-15", 
    "text": "Обновление алгоритма Google", 
    "service": "positions" 
  }'
```

### Get Notes
#### Method
POST

#### Endpoint
https://api.topvisor.com/get/annotations_2/

#### Parameters
##### Request Body
- **project_id** (integer) - Required - The ID of the project whose notes are to be retrieved.
- **limit** (integer) - Optional - The maximum number of notes to return (default 50).
- **offset** (integer) - Optional - The number of notes to skip (for pagination).

#### Request Example
```bash
curl -X POST "https://api.topvisor.com/get/annotations_2/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{ 
    "project_id": 12345, 
    "limit": 50, 
    "offset": 0 
  }'
```

#### Response
##### Success Response (200)
- **result** (array) - An array of note objects.
  - **id** (integer) - The unique identifier of the note.
  - **project_id** (integer) - The ID of the project.
  - **date** (string) - The date of the note.
  - **text** (string) - The content of the note.
  - **service** (string) - The service associated with the note.
- **total** (integer) - The total number of notes available.
- **errors** (null) - Null if no errors occurred.

##### Response Example
```json
{
  "result": [
    {
      "id": 999,
      "project_id": 12345,
      "date": "2024-01-15",
      "text": "Обновление алгоритма Google",
      "service": "positions"
    }
  ],
  "total": 25,
  "errors": null
}
```
```

--------------------------------

### TypeScript API Integration - TypeScript

Source: https://context7.com/topvisor/topvisor-openapi/llms.txt

Demonstrates how to leverage the provided TypeScript typings for the Topvisor API. It shows how to import types, extract path information, and use these types with the Fetch API for making requests. This enhances code autocompletion and type safety.

```typescript
import type { paths, operations } from 'topvisor-openapi/src/ts/Topvisor.ts';

// Извлечение типа пути API
type Path = keyof paths;

// Пример использования путей
const methodPath: Path = '/get/projects_2/projects/';
const positionsPath: Path = '/get/positions_2/history/';

// Извлечение имён сервисов из путей
type ExtractServicesNamesFromPaths<T> = T extends `/${string}/${infer P}/${string}` ? P : never;
type ServicesNames = ExtractServicesNamesFromPaths<Path>;
// ServicesNames = "projects_2" | "positions_2" | "keywords_2" | ...

// Использование с fetch API
async function getProjects(): Promise<void> {
  const response = await fetch('https://api.topvisor.com/get/projects_2/projects/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_TOKEN'
    },
    body: JSON.stringify({
      limit: 100,
      offset: 0,
      fields: ['id', 'name', 'url']
    })
  });

  const data = await response.json();
  console.log(data.result); // Типизированный результат
}

// Пример типа для тела запроса позиций
interface PositionsHistoryRequest {
  project_id: number;
  regions_indexes: number[];
  date1?: string;
  date2?: string;
  type_range?: number;
  limit?: number;
  offset?: number;
}
```