#CLI и cURL

Страница для тех, кто работает с Vibe API из терминала: скрипты для оболочки, разовые проверки утилитой curl, серверные интеграции на PHP без SDK. Полные справочники по операциям — на профильных страницах: Entity API, Фильтрация, Batch API, Коды ошибок.

Базовый URL — https://vibecode.bitrix24.tech. Авторизация — через заголовок X-Api-Key. Ответы — JSON в формате { success, data, meta } при успехе и { success: false, error } при ошибке.

#На странице

#Окружение

Сохраните ключ и базовый URL в переменные окружения — это убирает повторы в каждой команде и не оставляет ключ в истории команд оболочки.

Terminal 
export VIBE_API_KEY="vibe_api_xxx..."
export VIBE_URL="https://vibecode.bitrix24.tech"

Проверка — должен вернуться JSON с порталом и скоупами:

Terminal 
curl -s -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/me" | head -c 200

Чтобы переменные сохранились между сессиями, добавьте строки export ... в ~/.zshrc (для оболочки zsh) или ~/.bashrc (для bash) и перезапустите терминал.

Для ключа авторизации (vibe_app_...) дополнительно понадобится токен сессии:

Terminal 
export VIBE_APP_KEY="vibe_app_xxx..."
export VIBE_SESSION_TOKEN="vibe_session_xxx..."

#Авторизация в curl

Личный ключ — один заголовок:

Terminal 
curl -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/deals"

Ключ авторизации — два заголовка, X-Api-Key для приложения и Authorization: Bearer для сессии конкретного пользователя:

Terminal 
curl -H "X-Api-Key: $VIBE_APP_KEY" \
     -H "Authorization: Bearer $VIBE_SESSION_TOKEN" \
     "$VIBE_URL/v1/deals"

Подробнее о типах ключей и получении токена сессии — Ключи и авторизация.

#Минимальный цикл проверки

Один сценарий, чтобы убедиться, что ключ работает и API отвечает: создать сделку → удалить. Тот же набор операций есть для всех 40+ сущностей — отличаются только поля (см. Entity API и справочник сущностей).

Terminal 
# 1. Создать сделку — вернёт объект с присвоенным id
curl -X POST "$VIBE_URL/v1/deals" \
  -H "X-Api-Key: $VIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "CLI test", "stageId": "NEW", "categoryId": 0 }'

# 2. Удалить созданную сделку — успех = HTTP 204 с пустым телом
curl -i -X DELETE "$VIBE_URL/v1/deals/<id-из-первого-ответа>" \
  -H "X-Api-Key: $VIBE_API_KEY"

Признак успеха DELETE — код ответа, не тело ответа. Чтобы увидеть только код:

Terminal 
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE \
  -H "X-Api-Key: $VIBE_API_KEY" \
  "$VIBE_URL/v1/deals/<id>"

Полные примеры запросов с фильтрами, сортировкой, выбором полей и автопагинацией — на странице нужной сущности, например Сделки. Синтаксис фильтров (MongoDB-style, префиксы, операторы как ключи) — Фильтрация и поиск.

#Полезные приёмы curl

#Читаемый JSON в терминале

curl выдаёт ответ одной строкой. Для просмотра подключите jq или python3 -m json.tool:

Terminal 
curl -s -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/deals?limit=5" | jq
curl -s -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/deals?limit=5" | python3 -m json.tool

#`-s` против `-sS` в скриптах

Флаг -s (тихий режим) подавляет индикатор прогресса вместе с сообщениями о сетевых ошибках — например, Could not resolve host. В скриптах это скрывает реальные сбои. Флаг -sS подавляет только индикатор прогресса, а текст ошибки выводится в stderr:

Terminal 
# Тихо, но при сетевой ошибке скрипт молча получит пустой ответ
curl -s "$VIBE_URL/v1/deals" -H "X-Api-Key: $VIBE_API_KEY"

# Тихо для нормальной работы, ошибки сети видны
curl -sS "$VIBE_URL/v1/deals" -H "X-Api-Key: $VIBE_API_KEY"

В скриптах для оболочки используйте -sS: ошибки сети попадут в stderr и не потеряются при отладке.

#Большое тело запроса через `--data-binary @file.json`

При длинном теле (batch на 50 операций, импорт OpenAPI, развёрнутый фильтр) флаг -d не справляется с экранированием кавычек оболочки и переносами строк. Сохраните тело в файл и передайте его через @:

Terminal 
cat > body.json <<'EOF'
{
  "calls": [
    { "id": "newDeals", "entity": "deals", "action": "list",
      "params": { "filter": { "stageId": "NEW" }, "limit": 100 } },
    { "id": "user", "entity": "users", "action": "get", "entityId": 1 }
  ]
}
EOF

curl -X POST "$VIBE_URL/v1/batch" \
  -H "X-Api-Key: $VIBE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

--data-binary сохраняет переносы и кавычки как есть, в отличие от -d, который вырезает \n.

Ответ группирует результаты по id каждого вызова — results содержит данные, meta — статистику пагинации, summary — итог по всему пакету:

JSON 
{
  "success": true,
  "data": {
    "results": {
      "newDeals": [ { "id": 7720, "title": "Поставка серверов", "stageId": "NEW" } ],
      "user": { "id": 1, "name": "Иван Петров" }
    },
    "totals": { "newDeals": 311 },
    "meta": {
      "newDeals": { "total": 311, "returned": 100, "hasMore": true }
    },
    "errors": [],
    "summary": { "total": 2, "succeeded": 2, "failed": 0 }
  }
}

Полные правила batch (лимит 50 вызовов, стоимость в единицах rate-limit, поведение action: "list" с limit > 50) — Batch API.

#Экспорт ключа без сохранения в истории оболочки

Команда export VIBE_API_KEY="vibe_api_..." сохранится в ~/.zsh_history или ~/.bash_history — оттуда ключ может попасть на демонстрацию экрана или в резервную копию системы. Альтернатива — read -s: оболочка прочитает ключ без отображения на экране, в истории останется только команда read, без значения.

Terminal 
read -s VIBE_API_KEY && export VIBE_API_KEY
# курсор не двигается, вставляете ключ, Enter

Тот же приём подходит для VIBE_APP_KEY и VIBE_SESSION_TOKEN.

#Заголовки и код ответа

Terminal 
# -i — заголовки + тело
curl -i -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/me"

# -w — только выбранные поля статистики (код, время)
curl -s -o /dev/null -w "HTTP %{http_code}, %{time_total}s\n" \
  -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/deals"

#Лимиты запросов

В заголовках ответа приходят X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — текущий остаток лимита запросов для ключа:

Terminal 
curl -s -D - -o /dev/null -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/me" | grep -i ratelimit

#Сохранение ответа в файл

Terminal 
curl -s -H "X-Api-Key: $VIBE_API_KEY" "$VIBE_URL/v1/openapi.json" -o openapi.json

#OpenAPI-спецификация

Полный машинно-читаемый каталог эндпоинтов — /v1/openapi.json (в формате OpenAPI 3.0):

Terminal 
curl -s "$VIBE_URL/v1/openapi.json" -o openapi.json

Файл импортируется в Postman, Insomnia, Swagger UI и любые инструменты, поддерживающие OpenAPI 3.0. На основе спецификации можно генерировать клиентские библиотеки (openapi-generator, oazapfts и аналоги).

#Утилита `openapi-to-cli`

Сторонний инструмент, не часть Vibe API. Платформа не следит за его работоспособностью; за обновлениями, ошибками и совместимостью со спецификацией обращайтесь в репозиторий автора.

`openapi-to-cli` — CLI-утилита, которая собирает команды на основе любой OpenAPI-спецификации. Подключается к Vibe API без кодогенерации: указываете URL спецификации и заголовок авторизации.

Terminal 
npm install -g openapi-to-cli

ocli profile add vibecode \
  --spec https://vibecode.bitrix24.tech/v1/openapi.json \
  --base-url https://vibecode.bitrix24.tech \
  --header "X-Api-Key: $VIBE_API_KEY"

# Поиск эндпоинта по слову
ocli vibecode search "deals"

# Вызов
ocli vibecode exec GET /v1/deals
ocli vibecode exec POST /v1/deals \
  --body '{ "title": "Новая сделка", "stageId": "NEW", "categoryId": 0 }'

Утилита сторонняя, поддерживается своим автором — за обновлениями и ошибками обращайтесь в её репозиторий. После изменений в Vibe API обновлённая спецификация подхватывается ocli при следующем запуске.

#PHP

Минимальный шаблон для скриптов и серверных интеграций — без внешних зависимостей, только встроенный curl. Тот же шаблон подходит для всех эндпоинтов: vibeRequest($url, $method, $data).

php 
<?php

$VIBE_URL = getenv('VIBE_URL') ?: 'https://vibecode.bitrix24.tech';
$VIBE_API_KEY = getenv('VIBE_API_KEY') ?: 'vibe_api_xxx...';

function vibeRequest(string $url, string $method = 'GET', ?array $data = null): array {
    global $VIBE_API_KEY;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => [
            'X-Api-Key: ' . $VIBE_API_KEY,
            'Content-Type: application/json',
        ],
    ]);
    if ($data !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
    }

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    // DELETE возвращает 204 с пустым телом
    if ($httpCode === 204) {
        return ['success' => true];
    }

    $body = json_decode($response, true);
    if ($body === null) {
        throw new RuntimeException("HTTP $httpCode: некорректный JSON в ответе");
    }
    if (empty($body['success'])) {
        $code = $body['error']['code'] ?? 'UNKNOWN';
        $msg  = $body['error']['message'] ?? 'Неизвестная ошибка';
        throw new RuntimeException("$code: $msg (HTTP $httpCode)");
    }
    return $body;
}

#Примеры использования

php 
// Список
$result = vibeRequest("$VIBE_URL/v1/deals?limit=20");
foreach ($result['data'] as $deal) {
    echo $deal['id'] . ': ' . $deal['title'] . PHP_EOL;
}

// Создание
$result = vibeRequest("$VIBE_URL/v1/deals", 'POST', [
    'title'      => 'Поставка серверов',
    'stageId'    => 'NEW',
    'categoryId' => 0,
    'amount'     => 1500000,
    'currency'   => 'RUB',
]);
$dealId = $result['data']['id'];

// Поиск с фильтром
$result = vibeRequest("$VIBE_URL/v1/deals/search", 'POST', [
    'filter' => [
        'stageId' => ['$ne' => 'LOST'],
        'amount'  => ['$gte' => 100000],
    ],
    'sort'  => ['createdAt' => 'desc'],
    'limit' => 50,
]);

// Удаление — внутри vibeRequest 204 превращается в ['success' => true]
vibeRequest("$VIBE_URL/v1/deals/$dealId", 'DELETE');

Полные форматы тел запроса и поля ответа — на страницах конкретных сущностей, например Сделки.

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

При неуспехе тело ответа имеет вид { success: false, error: { code, message } } и соответствующий HTTP-статус. Пример — запрос без ключа:

Terminal 
curl -i "$VIBE_URL/v1/deals"
HTTP/2 401
content-type: application/json; charset=utf-8

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Полный справочник кодов и рекомендуемых действий — Коды ошибок.

#Связанные разделы