API - VK-IO

The API class provides a complete interface for calling VK API methods. It handles request queuing, rate limiting, error handling, and automatic retry logic.

Constructor

import { API } from 'vk-io';

const api = new API({
  token: 'your_access_token'
});

Typically, you don’t need to instantiate API directly. Use vk.api from the VK instance instead.

Parameters

options

Partial<IAPIOptions> & { token: string }

required

Configuration options for the API instance. See VK constructor options for all available options.

Properties

options

IAPIOptions

Current API configuration options. You can modify these at runtime:

vk.api.options.apiLimit = 5; // Increase rate limit
vk.api.updateWorker(); // Apply changes

Methods

call()

Makes a raw API method call.

const response = await api.call('users.get', {
  user_ids: [1]
});

method

string

required

VK API method name (e.g., users.get, messages.send).

params

object

required

Method parameters as key-value pairs.

response

API response data. Type can be specified with generic: api.call<User[]>(...)

execute()

Executes VKScript code on VK servers.

const result = await api.execute({
  code: 'return API.users.get({ user_ids: [1, 2, 3] });'
});

params

object

required

Show Parameters

code

string

required

VKScript code to execute on the server.

response

IExecuteResponse<T>

Execute response with results and any errors that occurred.

Show IExecuteResponse

response

Execution result.

errors

ExecuteError[]

Array of errors that occurred during execution.

procedure()

Calls a stored VKScript procedure.

const result = await api.procedure('myProcedure', {
  user_id: 123
});

name

string

required

Name of the stored procedure.

params

object

required

Parameters to pass to the procedure.

response

IExecuteResponse<T>

Procedure execution response.

callWithRequest()

Enqueues a custom API request for execution.

import { APIRequest } from 'vk-io';

const request = new APIRequest({
  api,
  method: 'users.get',
  params: { user_ids: [1] }
});

const response = await api.callWithRequest(request);

request

APIRequest

required

Custom API request instance.

response

Promise<T>

Promise that resolves with the API response.

updateWorker()

Updates the internal request worker when configuration changes.

vk.api.options.apiMode = 'parallel';
vk.api.updateWorker();

Call this after modifying API options at runtime to apply changes.

API Method Groups

The API class provides typed method groups for all VK API endpoints:

account

await vk.api.account.getInfo();
await vk.api.account.setOnline();

apps

const apps = await vk.api.apps.get({
  app_id: 123
});

audio

const audio = await vk.api.audio.get({
  owner_id: 123
});

board

const topics = await vk.api.board.getTopics({
  group_id: 123
});

database

const countries = await vk.api.database.getCountries();
const cities = await vk.api.database.getCities({
  country_id: 1
});

docs

const docs = await vk.api.docs.get({
  owner_id: 123
});

fave

const posts = await vk.api.fave.getPosts();

friends

const friends = await vk.api.friends.get({
  user_id: 123
});

await vk.api.friends.add({
  user_id: 456
});

gifts

const gifts = await vk.api.gifts.get({
  user_id: 123
});

groups

const groups = await vk.api.groups.get({
  user_id: 123
});

const group = await vk.api.groups.getById({
  group_id: 123
});

await vk.api.groups.join({
  group_id: 123
});

likes

await vk.api.likes.add({
  type: 'post',
  owner_id: 123,
  item_id: 456
});

market

const items = await vk.api.market.get({
  owner_id: -123
});

messages

await vk.api.messages.send({
  peer_id: 123,
  message: 'Hello!',
  random_id: 0
});

const history = await vk.api.messages.getHistory({
  peer_id: 123
});

newsfeed

const feed = await vk.api.newsfeed.get();

notes

const notes = await vk.api.notes.get();

notifications

const notifications = await vk.api.notifications.get();

photos

const albums = await vk.api.photos.getAlbums({
  owner_id: 123
});

const photos = await vk.api.photos.get({
  owner_id: 123,
  album_id: 'wall'
});

polls

const poll = await vk.api.polls.getById({
  poll_id: 123,
  owner_id: 456
});

stats

const stats = await vk.api.stats.get({
  group_id: 123
});

status

const status = await vk.api.status.get();
await vk.api.status.set({ text: 'New status' });

storage

await vk.api.storage.set({
  key: 'myKey',
  value: 'myValue'
});

const value = await vk.api.storage.get({
  key: 'myKey'
});

stories

const stories = await vk.api.stories.get();

users

const users = await vk.api.users.get({
  user_ids: [1, 2, 3],
  fields: ['photo_100', 'city', 'verified']
});

const search = await vk.api.users.search({
  q: 'John Doe'
});

utils

const shortUrl = await vk.api.utils.getShortLink({
  url: 'https://example.com'
});

const time = await vk.api.utils.getServerTime();

video

const videos = await vk.api.video.get({
  owner_id: 123
});

wall

const wall = await vk.api.wall.get({
  owner_id: 123
});

await vk.api.wall.post({
  owner_id: -123,
  message: 'New post!'
});

Examples

Basic API Calls

import { VK } from 'vk-io';

const vk = new VK({ token: process.env.VK_TOKEN });

// Get user information
const [user] = await vk.api.users.get({
  user_ids: [1],
  fields: ['photo_200', 'city', 'verified']
});

console.log(`${user.first_name} ${user.last_name}`);

Sending Messages

import { VK } from 'vk-io';

const vk = new VK({ token: process.env.VK_TOKEN });

await vk.api.messages.send({
  peer_id: 123456789,
  message: 'Hello from VK-IO!',
  random_id: Math.floor(Math.random() * 1000000)
});

Using Execute for Batch Requests

const { response, errors } = await vk.api.execute<any[]>({
  code: `
    var users = API.users.get({ user_ids: [1, 2, 3] });
    var groups = API.groups.getById({ group_id: 1 });
    return { users: users, groups: groups };
  `
});

console.log(response.users);
console.log(response.groups);

Error Handling

import { VK, APIError } from 'vk-io';

const vk = new VK({ token: process.env.VK_TOKEN });

try {
  await vk.api.messages.send({
    peer_id: 123,
    message: 'Hello',
    random_id: 0
  });
} catch (error) {
  if (error instanceof APIError) {
    console.error(`API Error ${error.code}: ${error.message}`);
    console.error('Request params:', error.params);
  }
}

Rate Limiting Configuration

const vk = new VK({
  token: process.env.VK_TOKEN,
  apiLimit: 20, // 20 requests per second
  apiMode: 'parallel', // Use execute batching
  apiExecuteCount: 25 // Batch up to 25 requests
});

// Make many requests - they'll be automatically rate limited and batched
const userIds = Array.from({ length: 100 }, (_, i) => i + 1);
const users = await Promise.all(
  userIds.map(id => vk.api.users.get({ user_ids: [id] }))
);

Working with Large Datasets

import { VK } from 'vk-io';

const vk = new VK({ token: process.env.VK_TOKEN });

async function getAllFriends(userId: number) {
  const friends = [];
  let offset = 0;
  const count = 5000; // Max allowed by VK
  
  while (true) {
    const response = await vk.api.friends.get({
      user_id: userId,
      offset,
      count
    });
    
    friends.push(...response.items);
    
    if (response.items.length < count) {
      break;
    }
    
    offset += count;
  }
  
  return friends;
}

const allFriends = await getAllFriends(123);
console.log(`Total friends: ${allFriends.length}`);

Best Practices

Use Typed Responses: Import types from vk-io for better TypeScript support:

import { API } from 'vk-io';
import type { UsersUserFull } from 'vk-io';

const users = await vk.api.users.get<UsersUserFull[]>({
  user_ids: [1],
  fields: ['photo_200']
});

Rate Limits: Always respect VK’s rate limits. The default apiLimit: 3 is safe for user tokens. Service tokens may allow higher limits.

Random ID for Messages: When sending messages, always provide a unique random_id to prevent duplicate sends:

await vk.api.messages.send({
  peer_id: 123,
  message: 'Hello',
  random_id: Math.floor(Math.random() * 2147483647)
});

Core Classes

Structures

Utilities

​Constructor

​Parameters

​Properties

​Methods

​call()

​execute()

​procedure()

​callWithRequest()

​updateWorker()

​API Method Groups

​account

​apps

​audio

​board

​database

​docs

​fave

​friends

​gifts

​groups

​likes

​market

​messages

​newsfeed

​notes

​notifications

​photos

​polls

​stats

​status

​storage

​stories

​users

​utils

​video

​wall

​Examples

​Basic API Calls

​Sending Messages

​Using Execute for Batch Requests

​Error Handling

​Rate Limiting Configuration

​Working with Large Datasets

​Best Practices

Build docs developers (and LLMs) love

Constructor

Parameters

Properties

Methods

call()

execute()

procedure()

callWithRequest()

updateWorker()

API Method Groups

account

apps

audio

board

database

docs

fave

friends

gifts

groups

likes

market

messages

newsfeed

notes

notifications

photos

polls

stats

status

storage

stories

users

utils

video

wall

Examples

Basic API Calls

Sending Messages

Using Execute for Batch Requests

Error Handling

Rate Limiting Configuration

Working with Large Datasets

Best Practices