API Module

Make requests to VK API methods with automatic rate limiting and execution modes

The API module is the core interface for making requests to VK API methods. It provides automatic rate limiting, request batching, and flexible execution modes.

Initialization

import { API } from 'vk-io';

const api = new API({
  token: process.env.VK_TOKEN
});

Making API Calls

VK-IO provides a convenient proxy-based interface for calling API methods. Simply copy the method name from VK API documentation:

const users = await api.users.get({
  user_ids: 1
});

console.log(users); // [{ id: 1, first_name: 'Pavel', last_name: 'Durov' }]

Under the hood, api.users.get() is equivalent to:

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

The proxy interface provides full TypeScript autocompletion for all VK API methods.

Configuration Options

Rate Limiting

By default, VK-IO limits requests to 3 per second (user tokens and service keys):

apiLimit · number · default: 3

Requests per second. For group tokens, use 20

apiWait · number · default: 3000

Time to wait (in ms) before re-querying after rate limit error

const api = new API({
  token: process.env.GROUP_TOKEN,
  apiLimit: 20  // Group token limit
});

Request Modes

sequential

Default mode. Sends requests one by one.

const api = new API({
  token: process.env.TOKEN,
  apiMode: 'sequential'
});

• 1 method = 1 request
• Safest option
• Best for low-volume applications

parallel

Batches methods using execute to send up to 25 methods in one request.

const api = new API({
  token: process.env.TOKEN,
  apiMode: 'parallel',
  apiExecuteCount: 25  // Methods per execute call
});

• 1-25 methods = 1 request
• Significantly faster for bulk operations
• Some methods cannot be batched (see apiExecuteUnsupportedMethods)

parallel_selected

Batches only specific methods via execute, others use sequential mode.

const api = new API({
  token: process.env.TOKEN,
  apiMode: 'parallel_selected',
  apiExecuteMethods: ['messages.send', 'users.get']
});

• Hybrid approach
• Optimizes specific high-volume methods
• Other methods run sequentially

apiExecuteUnsupportedMethods · string[]

Methods that cannot be batched in execute (mainly upload methods):

[
  'photos.save',
  'photos.saveWallPhoto',
  'photos.saveMessagesPhoto',
  'messages.setChatPhoto',
  'audio.save',
  'docs.save',
  'stories.save',
  'polls.savePhoto'
]

Request Timing Mode

sequential

Default. Sends requests with interval 1000ms / apiLimit.

const api = new API({
  apiRequestMode: 'sequential',
  apiLimit: 3  // ~333ms between requests
});

burst

Sends all requests immediately up to apiLimit.

const api = new API({
  apiRequestMode: 'burst',
  apiLimit: 20
});

May cause EAI_AGAIN errors due to DNS resolution limits. Use with caution.

Execute Methods

Custom Execute Code

Run custom VKScript code:

const { response, errors } = await api.execute({
  code: `
    var users = API.users.get({user_ids: Args.ids});
    var groups = API.groups.getById({group_ids: Args.gids});
    
    return {
      users: users,
      groups: groups
    };
  `,
  ids: [1, 2, 3],
  gids: [1, 2]
});

console.log(response); // { users: [...], groups: [...] }
console.log(errors);   // ExecuteError[]

execute returns {response, errors} format instead of just response.

Stored Procedures

Call stored procedures from your VK application:

const { response, errors } = await api.procedure('myProcedure', {
  param1: 'value',
  param2: 123
});

// Equivalent to:
// await api.call('execute.myProcedure', { ... });

Advanced Configuration

Retry Logic

apiRetryLimit · number · default: 3

Number of retries for failed requests

apiTimeout · number · default: 10000

Request timeout in milliseconds

const api = new API({
  token: process.env.TOKEN,
  apiRetryLimit: 5,
  apiTimeout: 15000
});

Custom Headers

apiHeaders · Record<string, string>

Custom headers for API requests

const api = new API({
  token: process.env.TOKEN,
  apiHeaders: {
    'User-Agent': 'MyBot/1.0'
  }
});

Language Setting

language · 'ru' | 'uk' | 'be' | 'en' | 'es' | 'fi' | 'de' | 'it'

Response data language

const api = new API({
  token: process.env.TOKEN,
  language: 'en'
});

Using Proxy

Pass an HTTPS agent to use a proxy:

import { API } from 'vk-io';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080');

const api = new API({
  token: process.env.TOKEN,
  agent
});

Captcha Handling

Handle captcha challenges with a callback service:

import { API, CallbackService } from 'vk-io';

const callbackService = new CallbackService();

const api = new API({
  token: process.env.TOKEN,
  callbackService
});

callbackService.onCaptcha(async (payload, retry) => {
  console.log('Captcha required:', payload.redirectUri);
  
  // Solve captcha (use your preferred service)
  const { successToken, cookie } = await solveCaptcha(payload.redirectUri);
  
  // Set cookie if needed
  if (payload.request) {
    payload.request.headers.cookie = cookie;
  }
  
  try {
    await retry(successToken);
    console.log('Captcha solved successfully');
  } catch (error) {
    console.error('Failed to solve captcha');
  }
});

The captcha image URL can only be loaded once. Loading it multiple times generates a new captcha.

APIRequest Class

For advanced use cases, work directly with APIRequest:

import { API, APIRequest } from 'vk-io';

const api = new API({ token: process.env.TOKEN });

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

// Get execute code representation
const executeCode = String(request);
console.log(executeCode); // API.users.get({"user_ids":1})

// Execute the request
const response = await api.callWithRequest(request);

// Access the promise directly
await request.promise;

Available API Groups

All VK API method groups are available:

api.account.*
api.ads.*
api.appWidgets.*
api.apps.*
api.audio.*
api.auth.*
api.board.*
api.database.*
api.docs.*
api.fave.*
api.friends.*
api.gifts.*
api.groups.*
api.leads.*
api.leadForms.*
api.likes.*
api.market.*
api.messages.*
api.newsfeed.*
api.notes.*
api.notifications.*
api.orders.*
api.pages.*
api.photos.*
api.places.*
api.polls.*
api.podcasts.*
api.prettyCards.*
api.search.*
api.secure.*
api.stats.*
api.status.*
api.storage.*
api.stories.*
api.streaming.*
api.users.*
api.utils.*
api.video.*
api.wall.*
api.widgets.*

See the VK API Reference for complete method documentation.