Получить список эпиков tasks.api.scrum.epic.list

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: task

Кто может выполнять метод: любой пользователь

Метод возвращает список эпиков.

Параметры метода

Название
тип

Описание

order
array

Массив для сортировки результата вида {'поле_сортировки': 'направление сортировки' [, ...]}.

Направление сортировки может принимать значения:

  • asc — по возрастанию
  • desc — по убыванию

Возможные значения элементов массива соответствуют полям ответа tasks.api.scrum.epic.add

filter
array

Массив вида {'фильтруемое_поле': 'значение фильтра' [, ...]}.

Ключу может быть задан дополнительный префикс, уточняющий поведение фильтра.

Возможные значения префикса:

  • = — равно (работает и с массивами)
  • % — LIKE, поиск по подстроке. Символ % в значении фильтра передавать не нужно. Поиск ищет подстроку в любой позиции строки
  • > — больше
  • < — меньше
  • != — не равно
  • !% — NOT LIKE, поиск по подстроке. Символ % в значении фильтра передавать не нужно. Поиск идет с обоих сторон.
  • >= — больше либо равно
  • <= — меньше либо равно
  • =% — LIKE, поиск по подстроке. Символ % нужно передавать в значении. Примеры:
    • "мол%" — ищем значения начинающиеся с «мол»
    • "%мол" — ищем значения заканчивающиеся на «мол»
    • "%мол%" — ищем значения, где «мол» может быть в любой позиции
  • %= — LIKE (смотрите описание выше)
  • !=% — NOT LIKE, поиск по подстроке. Символ % нужно передавать в значении. Примеры:
    • "мол%" — ищем значения не начинающиеся с «мол»
    • "%мол" — ищем значения не заканчивающиеся на «мол»
    • "%мол%" — ищем значения, где подстроки «мол» нет в любой позиции
  • !%= — NOT LIKE (смотрите описание выше)

Возможные значения элементов массива соответствуют полям ответа tasks.api.scrum.epic.add

select
array

Массив полей записей, которые будут возвращены методом.

Возможные значения элементов массива соответствуют полям ответа tasks.api.scrum.epic.add. Можно указать только те поля, которые необходимы.

Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию — пустой массив array(). Это означает, что будут возвращены все поля основной таблицы запроса

start
integer

Номер страницы вывода. Работает для https запросов.

Размер страницы результатов всегда статичный: 50 записей.

Чтобы выбрать вторую страницу результатов необходимо передавать значение 50. Чтобы выбрать третью страницу результатов значение — 100 и так далее.

Формула расчета значения параметра start:
start = (N-1) * 50, где N — номер нужной страницы

Примеры кода

Как использовать примеры в документации

curl -X POST \
        -H "Content-Type: application/json" \
        -d '{
            "filter": {
                "GROUP_ID": 143,
                ">=ID": 1,
                "<=ID": 50,
                "NAME": "%эпик%",
                "!=DESCRIPTION": "old epic",
            },
            "order": {
                "ID": "asc",
                "NAME": "desc"
            },
            "select": ["ID", "NAME", "DESCRIPTION", "CREATED_BY", "MODIFIED_BY", "COLOR"],
            "start": 0
        }' \
        https://your-domain.bitrix24.com/rest/_USER_ID_/_CODE_/tasks.api.scrum.epic.list
        
curl -X POST \
        -H "Content-Type: application/json" \
        -d '{
            "filter": {
                "GROUP_ID": 143,
                ">=ID": 1,
                "<=ID": 50,
                "NAME": "%эпик%",
                "!=DESCRIPTION": "old epic",
                "CREATED_BY": 1,
                "MODIFIED_BY": 3,
                "COLOR": "#69dafc"
            },
            "order": {
                "ID": "asc",
                "NAME": "desc"
            },
            "select": ["ID", "NAME", "DESCRIPTION", "CREATED_BY", "MODIFIED_BY", "COLOR"],
            "start": 0,
            "auth": "YOUR_ACCESS_TOKEN"
        }' \
        https://your-domain.bitrix24.com/rest/tasks.api.scrum.epic.list
        
// callListMethod: Получает все данные сразу. Используйте только для небольших выборок (< 1000 элементов) из-за высокой нагрузки на память.
        
        const groupId = 143;
        try {
          const response = await $b24.callListMethod(
            'tasks.api.scrum.epic.list',
            {
              filter: {
                GROUP_ID: groupId,
                '>=ID': 1,
                '<=ID': 50,
                'NAME': '%эпик%',
                '!=DESCRIPTION': 'old epic',
                'CREATED_BY': 1,
                'MODIFIED_BY': 3,
                'COLOR': '#69dafc'
              },
              order: {
                'ID': 'asc',
                'NAME': 'desc'
              },
              select: ['ID', 'NAME', 'DESCRIPTION', 'CREATED_BY', 'MODIFIED_BY', 'COLOR'],
              start: 0
            },
            (progress) => { console.log('Progress:', progress) }
          );
          const items = response.getData() || [];
          for (const entity of items) { console.log('Entity:', entity); }
        } catch (error) {
          console.error('Request failed', error);
        }
        
        // fetchListMethod: Выбирает данные по частям с помощью итератора. Используйте для больших объемов данных для эффективного потребления памяти.
        
        const groupId = 143;
        try {
          const generator = $b24.fetchListMethod('tasks.api.scrum.epic.list', {
            filter: {
              GROUP_ID: groupId,
              '>=ID': 1,
              '<=ID': 50,
              'NAME': '%эпик%',
              '!=DESCRIPTION': 'old epic',
              'CREATED_BY': 1,
              'MODIFIED_BY': 3,
              'COLOR': '#69dafc'
            },
            order: {
              'ID': 'asc',
              'NAME': 'desc'
            },
            select: ['ID', 'NAME', 'DESCRIPTION', 'CREATED_BY', 'MODIFIED_BY', 'COLOR'],
            start: 0
          }, 'ID');
          for await (const page of generator) {
            for (const entity of page) { console.log('Entity:', entity); }
          }
        } catch (error) {
          console.error('Request failed', error);
        }
        
        // callMethod: Ручное управление постраничной навигацией через параметр start. Используйте для точного контроля над пакетами запросов. Для больших данных менее эффективен, чем fetchListMethod.
        
        const groupId = 143;
        try {
          const response = await $b24.callMethod('tasks.api.scrum.epic.list', {
            filter: {
              GROUP_ID: groupId,
              '>=ID': 1,
              '<=ID': 50,
              'NAME': '%эпик%',
              '!=DESCRIPTION': 'old epic',
              'CREATED_BY': 1,
              'MODIFIED_BY': 3,
              'COLOR': '#69dafc'
            },
            order: {
              'ID': 'asc',
              'NAME': 'desc'
            },
            select: ['ID', 'NAME', 'DESCRIPTION', 'CREATED_BY', 'MODIFIED_BY', 'COLOR'],
            start: 0
          }, 0);
          const result = response.getData().result || [];
          for (const entity of result) { console.log('Entity:', entity); }
        } catch (error) {
          console.error('Request failed', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'tasks.api.scrum.epic.list',
                    [
                        'filter' => [
                            'GROUP_ID'      => $groupId,
                            '>=ID'          => 1,
                            '<=ID'          => 50,
                            'NAME'          => '%эпик%',
                            '!=DESCRIPTION' => 'old epic',
                            'CREATED_BY'    => 1,
                            'MODIFIED_BY'   => 3,
                            'COLOR'         => '#69dafc'
                        ],
                        'order'  => [
                            'ID'   => 'asc',
                            'NAME' => 'desc'
                        ],
                        'select' => ['ID', 'NAME', 'DESCRIPTION', 'CREATED_BY', 'MODIFIED_BY', 'COLOR'],
                        'start'  => 0
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error: ' . $e->getMessage();
        }
        
const groupId = 143;
        BX24.callMethod(
            'tasks.api.scrum.epic.list',
            {
                filter: {
                    GROUP_ID: groupId,
                    '>=ID': 1,
                    '<=ID': 50,
                    'NAME': '%эпик%',
                    '!=DESCRIPTION': 'old epic',
                    'CREATED_BY': 1,
                    'MODIFIED_BY': 3,
                    'COLOR': '#69dafc'
                },
                order: {
                    'ID': 'asc',
                    'NAME': 'desc'
                },
                select: ['ID', 'NAME', 'DESCRIPTION', 'CREATED_BY', 'MODIFIED_BY', 'COLOR']
            },
            function(res)
            {
                if (res.error())
                {
                    console.error(res.error());
                    return;
                }
        
                console.log(res.data());
        
                if (res.more())
                {
                    res.next();
                }
            }
        );
        
require_once('crest.php'); // подключение CRest PHP SDK
        
        // выполнение запроса к REST API
        $result = CRest::call(
            'tasks.api.scrum.epic.list',
            [
                'filter' => [
                    'GROUP_ID' => 143,
                    '>=ID' => 1,
                    '<=ID' => 50,
                    'NAME' => '%эпик%',
                    '!=DESCRIPTION' => 'old epic',
                    'CREATED_BY' => 1,
                    'MODIFIED_BY' => 3,
                    'COLOR' => '#69dafc'
                ],
                'order' => [
                    'ID' => 'asc',
                    'NAME' => 'desc'
                ],
                'select' => ['ID', 'NAME', 'DESCRIPTION', 'CREATED_BY', 'MODIFIED_BY', 'COLOR'],
                'start' => 0
            ]
        );
        
        // Обработка ответа от Битрикс24
        if ($result['error']) {
            echo 'Error: '.$result['error_description'];
        }
        else {
            print_r($result['result']);
        }
        

Обработка ответа

HTTP-статус: 200

[
            {
                "id": 1,
                "groupId": 143,
                "name": "эпик",
                "description": "",
                "createdBy": 1,
                "modifiedBy": 0,
                "color": "#69dafc"
            },
            {
                "id": 3,
                "groupId": 143,
                "name": "эпик2",
                "description": "new epic",
                "createdBy": 3,
                "modifiedBy": 5,
                "color": "#69dagc"
            }
        ]
        

Возвращаемые данные

Название
тип

Описание

id
integer

Идентификатор эпика

groupId
integer

Идентификатор группы (скрама), к которой привязан эпик

name
string

Название эпика

description
string

Описание эпика

createdBy
integer

Идентификатор пользователя, создавшего эпик

modifiedBy
integer

Идентификатор пользователя, который последним изменял эпик

color
string

Цвет эпика в формате HEX

Обработка ошибок

HTTP-статус: 400

{
            "error": 0,
            "error_description": "Could not load list"
        }
        

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные коды ошибок

Код

Описание

Значение

0

Could not load list

Не найдено ни одного эпика с указанными фильтрами

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически через 10 минут

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение