---
title: "Introduction to working with Bitrix24 REST API"
description: "Overview of SDK capabilities for working with Bitrix24 REST API"
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/working-with-the-rest-api"
last_updated: "2026-05-08"
---
# Introduction to working with Bitrix24 REST API

> Overview of SDK capabilities for working with Bitrix24 REST API

> [!WARNING]
> We are still updating this page. Some data may be missing here — we will complete it shortly.

## Overview

The SDK for working with Bitrix24 REST API provides a set of tools for interacting with Bitrix24 API from JavaScript/TypeScript applications.

<rest-api-version-only>
<template v-slot:rest-api-ver2="">

The library supports both REST API version 2 (deprecation process has started but still widely used) and the new version 3 (implementation process has started).

</template>
</rest-api-version-only>

## SDK Architecture

The SDK is built on three main classes that inherit from a common base class and provide a unified interface for working with REST API:

### Three Classes for Different Usage Scenarios

| Класс | Назначение | Где использовать | Особенности |
| --- | --- | --- | --- |
| `B24Frame` | Working from applications embedded in the Bitrix24 interface | Client-side (browser) | Automatically available in Bitrix24 application iframe, uses current user token |
| `B24Hook` | Working from standalone server applications via webhook | Server-side | Uses permanent webhook token, **cannot be used in browser** |
| `B24OAuth` | Working from standalone server applications via OAuth 2.0 | Server-side | Uses OAuth token with refresh capability, **cannot be used in browser** |

### Common Interface

All three classes inherit from a common base class and provide the same set of methods:

<rest-api-version-only>
<template v-slot:rest-api-ver2="">

```ts
// Unified interface for all classes
interface B24Base {
  actions: {
    v2: {
      call: { make(options: ActionCallV2): Promise<AjaxResult> }
      callList: { make(options: ActionCallListV2): Promise<Result<T[]>> }
      fetchList: { make(options: ActionFetchListV2): AsyncGenerator<T[]> }
      batch: { make(options: ActionBatchV2): Promise<CallBatchResult> }
      batchByChunk: { make(options: ActionBatchByChunkV2): Promise<Result<T[]>> }
    }
    // ... other methods
  }
  
  tools: {
    healthCheck: { make(options?: { requestId?: string }): Promise<boolean> }
    ping: { make(options?: { requestId?: string }): Promise<number> }
    // ... other methods
  }
}
```

</template>

<template v-slot:rest-api-ver3="">

```ts
// Unified interface for all classes
interface B24Base {
  actions: {
    v3: {
      call: { make(options: ActionCallV3): Promise<AjaxResult> }
      callList: { make(options: ActionCallListV3): Promise<Result<T[]>> }
      fetchList: { make(options: ActionFetchListV3): AsyncGenerator<T[]> }
      batch: { make(options: ActionBatchV3): Promise<CallBatchResult> }
      batchByChunk: { make(options: ActionBatchByChunkV3): Promise<Result<T[]>> }
    }
    // ... other methods
  }
  
  tools: {
    healthCheck: { make(options?: { requestId?: string }): Promise<boolean> }
    ping: { make(options?: { requestId?: string }): Promise<number> }
    // ... other methods
  }
}
```

</template>
</rest-api-version-only>

## Key Features

### Main API Methods

- **Call** — basic method for calling any REST API methods
- **CallList** — automatic retrieval of all data from list methods with pagination
- **FetchList** — step-by-step processing of large data volumes via AsyncGenerator
- **Batch** — execution of up to 50 commands in a single request
- **BatchByChunk** — automatic splitting of large command sets into batches

### Helper Tools

- **HealthCheck** — checking REST API availability
- **Ping** — measuring API response time

## Choosing the Right Class

### For Client Applications (Browser) `client-side`

Use `B24Frame` — it's available in [Bitrix24 application iframes](https://bitrix24.github.io/b24jssdk/raw/docs/getting-started/installation/vue.md#init):

<rest-api-version-only>
<template v-slot:rest-api-ver2="">

```ts
// In an application embedded in Bitrix24
async () => {
  $b24 = await initializeB24Frame()
  const response = await B24Frame.actions.v2.call.make({
    method: 'crm.contact.get',
    params: { id: 123 }
  })
}
```

</template>

<template v-slot:rest-api-ver3="">

```ts
// In an application embedded in Bitrix24
async () => {
  $b24 = await initializeB24Frame()
  const response = await B24Frame.actions.v3.call.make({
    method: 'tasks.task.get',
    params: { id: 123 }
  })
}
```

</template>
</rest-api-version-only>

### For Server Applications with Permanent Access `server-side`

Use `B24Hook` with webhook:

<rest-api-version-only>
<template v-slot:rest-api-ver2="">

```ts
import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

const response = await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 },
  requestId: 'server-request'
})
```

</template>

<template v-slot:rest-api-ver3="">

```ts
import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

const response = await $b24.actions.v3.call.make({
  method: 'tasks.task.get',
  params: { id: 123 },
  requestId: 'server-request'
})
```

</template>
</rest-api-version-only>

### For Server Applications with OAuth Authentication `server-side` `authentication`

Use `B24OAuth`:

<rest-api-version-only>
<template v-slot:rest-api-ver2="">

```ts
import { B24OAuth } from '@bitrix24/b24jssdk'

const $b24 = B24OAuth.fromConfig({
  domain: 'your_domain.bitrix24.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  accessToken: 'current_token',
  refreshToken: 'refresh_token'
})

const response = await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 },
  requestId: 'oauth-request'
})
```

</template>

<template v-slot:rest-api-ver3="">

```ts
import { B24OAuth } from '@bitrix24/b24jssdk'

const $b24 = B24OAuth.fromConfig({
  domain: 'your_domain.bitrix24.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  accessToken: 'current_token',
  refreshToken: 'refresh_token'
})

const response = await $b24.actions.v3.call.make({
  method: 'tasks.task.get',
  params: { id: 123 },
  requestId: 'oauth-request'
})
```

</template>
</rest-api-version-only>

## Common Methods (Available in All Classes)

### Method Architecture

| Method | Return Value | Memory | Usage | Suitable for |
| --- | --- | --- | --- | --- |
| `Call` | `PromiseAjaxResult>` | Minimum | Single calls | Retrieving individual elements, calling methods without pagination |
| `CallList` | `PromiseResultT[]>>` | All data in memory | `awaitresponse.getData()` | Small to medium data volumes, when all data is needed at once |
| `FetchList` | `AsyncGeneratorT[]>` | Processing in parts | `forawait(constchunkofgenerator)` | Large data volumes, stream processing, limited memory |
| `Batch` | `PromiseCallBatchResult>` | Depends on volume | Batch operations up to 50 commands | Bulk operations, network request optimization |

<rest-api-version-only>
<template v-slot:rest-api-ver2="">

> **Automatic Warnings**
> SDK automatically tracks usage of methods available in REST API v3:
> ```json
> "The method {method_name} is available in restApi:v3. It's worth migrating to the new API."
> ```
> This allows gradual migration from deprecated API v2 to modern v3.

</template>
</rest-api-version-only>

## Method Selection Recommendations

### For Data Retrieval

1. **Individual elements** → Use `Call`
2. **Small lists (up to 1000 records)** → Use `CallList`
3. **Large lists (thousands of records)** → Use `FetchList`
4. **Multiple individual elements** → Use `Batch`

### For Data Modification

1. **Single operations** → Use `Call`
2. **Bulk operations (up to 50)** → Use `Batch`
3. **Bulk operations (more than 50)** → Use `BatchByChunk`

### For Debugging and Monitoring

1. **Checking API availability** → Use `HealthCheck`
2. **Measuring response speed** → Use `Ping`

## Best Practices

### Error Handling

Always check `isSuccess` and handle errors:

<rest-api-version-only>
<template v-slot:rest-api-ver2="">

```typescript
const response = await $b24.actions.v2.call.make({
  method: 'some.method',
  params: { /* parameters */ },
  requestId: 'unique-id'
})

if (!response.isSuccess) {
  console.error('Error:', response.getErrorMessages().join('; '))
  // Additional error handling logic
  return
}

// Working with successful result
const data = response.getData()
```

</template>

<template v-slot:rest-api-ver3="">

```typescript
const response = await $b24.actions.v3.call.make({
  method: 'some.method',
  params: { /* parameters */ },
  requestId: 'unique-id'
})

if (!response.isSuccess) {
  console.error('Error:', response.getErrorMessages().join('; '))
  // Additional error handling logic
  return
}

// Working with successful result
const data = response.getData()
```

</template>
</rest-api-version-only>

### Request Management

- `requestId` — always specify a unique request identifier for tracking and deduplication
- **Logging** — use built-in logging mechanisms for debugging
- **Timeouts** — configure timeouts for long operations

## Migration from REST API v2 to v3

Bitrix24 is gradually transitioning to REST API version 3. It is recommended to:

1. **Monitor warnings** from SDK about method availability in v3
2. **Use** [REST API v3 documentation](https://apidocs.bitrix24.com/api-reference/rest-v3/index.html)
3. **Plan migration** of existing projects

## What's Next?

- **Common methods** — You have already familiarized yourself with common methods available in all three classes
- **Individual features** — Each class (`B24Frame`, `B24Hook`, `B24OAuth`) has its own unique methods and features that will be described in separate documentation sections
- **Usage examples** — See specific examples for each usage scenario

## Additional Resources

- [Official Bitrix24 REST API Documentation](https://apidocs.bitrix24.com/)
- [Recommendations for working with large data](https://apidocs.bitrix24.com/settings/performance/huge-data.html)

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.