# bk-console API v1 > Указатель для моделей и разработчиков, которые работают с API клиентской панели bk-console.com: Целевые клики по выдаче Яндекса — проекты с ключами, разовые задания «сайт + запрос + регион» с итогом вебхуком, забор заданий с сервера клиента по API.md, субаккаунты реселлера. Здесь — авторизация, права, порядок работы и лимиты. Точные схемы — в OpenAPI, всё вместе с примерами — в /llms-full.md. Базовый путь: `https://bk-console.com/api/v1`. Только HTTPS. Перед составлением запроса прочитайте метод в OpenAPI или в /llms-full.md. Не придумывайте методы, параметры и поля ответа. Этот файл — навигация, а не замена схемы. ## Документация - [Вся документация одним файлом](/llms-full.md): термины, правила, все методы с примерами curl и ответа, тексты ошибок, вебхук с проверкой подписи на Python и Node, забор по API.md. Отдайте его модели целиком. - [OpenAPI JSON](/openapi.json): схемы запросов и ответов, обязательные поля, допустимые значения; тексты ошибок метода — в `x-errors`. - [Документация для человека](/api-docs). ## Авторизация и права Передавайте ключ API в заголовке `X-Auth-Token: bk_…`. Не в URL и не как Bearer. Ключ выпускается на экране «Профиль» панели и показывается один раз. Тело запроса — JSON с `Content-Type: application/json`. Запрос выполняется с правами аккаунта ключа. Заблокированный аккаунт получает 403 и по ключу. Вызывайте API с сервера: CORS закрыт, браузер со стороннего сайта запрос не выполнит. | Кто | Что может | |---|---| | клиент | свои проекты, разовые задания, вебхук, Источник заданий, баланс и операции | | реселлер | всё, что клиент, и субаккаунты: создать, перевести деньги, поставить цену клика, заблокировать, выдать ссылку входа | | субаккаунт | как клиент; своих субаккаунтов не имеет | Ключами API управляют только из панели: `/account/keys*` по ключу отвечают 403. ## Методы Пути — от `/api/v1`. - Аккаунт: `GET /account` — проверка ключа; `GET /balance`; `GET /transactions`; `GET /performance` — план и факт за сутки. - Проекты: `GET`, `POST /projects` — создать или заменить все ключи сайта; `GET`, `PATCH`, `DELETE /projects/{id}`; `PATCH /projects/{id}/status` — вкл/выкл; `GET`, `PUT` (добавить и обновить, до 500), `PATCH` (вкл/выкл), `DELETE /projects/{id}/keys`; `POST /projects/{id}/boost`; `GET /projects/{id}/stats`, `GET /projects/{id}/keys/stats` (`?only=not_found&sort=not_found` — ключи, по которым сайт не находится, с подсказкой причины). - Разовые задания: `POST /tasks` — до 500 за вызов; `GET /tasks`, `GET /tasks/{id}`; `POST /tasks/cancel`; `GET`, `DELETE /queue`. - Вебхук: `GET`, `PUT /webhook`; `POST /webhook/secret` — секрет подписи, показывается один раз; `POST /webhook/test`. - Источник заданий (API.md): `GET`, `PUT /source` — два полных адреса вашего сервера: `task_url` (панель шлёт `GET` ровно на него) и `result_url` (`POST` итога), ничего не дописывая. Прежнее поле `url` (база, к ней дописываются `/task` и `/result`) принимается вместо них, но не вместе с ними. - Субаккаунты (реселлер): `GET`, `POST /subaccounts`; `GET`, `PATCH /subaccounts/{id}`; `POST /subaccounts/{id}/transfer`; `POST /subaccounts/{id}/login-link`; `GET /subaccounts/report`. ## Формат Ответ без ошибки — `{"ok": true, "data": …}`. Список несёт ещё `next_cursor`: следующая страница — тот же запрос с `cursor=`, `null` — страниц больше нет. `limit` — 1–500, умолчание 100; у отчётов — 1–100. Ошибка — `{"ok": false, "error": "текст"}` с HTTP 4xx или 5xx. Тексты ошибок каждого метода перечислены дословно: ветвитесь по ним. Исключения — ответы nginx 413 (тело больше 2 МиБ), 502 и 504: у них тело HTML, проверяйте `Content-Type` до разбора JSON. Неизвестное поле тела — 400 `<поле>: неизвестное поле` у методов, где этот текст есть в таблице ошибок; остальные методы неизвестные поля пропускают молча. Деньги — целые копейки (`*_kop`). Время — ISO 8601 UTC до секунд: `2026-11-20T07:15:00+00:00`. Сутки статистики и даты `date_from`, `date_to` — МСК. ## Разовые задания: порядок работы 1. `PUT /webhook {"url": "https://…"}` — один раз. Затем `POST /webhook/secret`: секрет подписи показывается один раз, сохраните его. Проверка — `POST /webhook/test`. 2. `POST /tasks` с заголовком `Idempotency-Key` (новый на каждую пачку) и своим `id` у каждого задания. 3. Ждите вебхук `task.finished` или опрашивайте `GET /tasks/{id}` (id панели из ответа) не чаще раза в минуту. 4. Итог: `status: done`, `result.outcome` — `clicked` (позиция и `found_url`) или `not_found`. Списание — цена клика аккаунта за оба итога. `expired`, `rejected`, `canceled` — без списания. Срок задания — 60 минут от приёма. Задание во флоте (`running`) ждёт итога ещё 5 минут после срока: итог в эти минуты — `done` со списанием. Проверяйте подпись вебхука: `X-BK-Signature = sha256=." + сырое тело)>`. ## Лимиты и ошибки Лимит — запросов в календарную минуту на аккаунт: общий `all` 60 и лимит метода сверх него: `write` 20, `boost` 1, `stats` 12, `tasks` 15, `money` 30, `login_link` 30. Превышение — 429 и заголовок `Retry-After` в секундах: ждите столько. `POST /webhook/test` из панели тоже считается в `tasks`. 401 — нет ключа, он неверный или отозван. 402 — не хватает денег. 403 — нет прав, аккаунт заблокирован или метод только для панели. 404 — объекта нет или он чужой. 409 — конфликт (повтор `Idempotency-Key` с другим телом, логин занят). 400 — ошибка параметров, текст называет поле. 502 — флот не принял запись: повторите позже. 503 — разовые задания выключены. 500 — `внутренняя ошибка сервера: повторите позже`. Путь с `/` на конце — 307 с пустым телом: пишите путь без `/`. ## Необратимые действия Изменяющие запросы (POST, PUT, PATCH, DELETE) выполняйте, только когда пользователь поручил именно это действие и назвал его область. Не используйте их для проверки соединения: для неё есть `GET /account`. | Действие | Что нельзя вернуть | |---|---| | `POST /projects` с доменом существующего проекта | все ключи проекта заменяются; удалённые ключи пропадают | | `DELETE /projects/{id}/keys` | ключи удаляются из флота | | `DELETE /queue` без фильтров | снимаются все задания аккаунта в работе, в том числе задания Источника | | `POST /webhook/secret` | прежний секрет перестаёт действовать сразу | | `POST /subaccounts/{id}/transfer` | деньги перемещаются сразу | | `POST /projects/{id}/boost` | лимиты всех ключей меняются; обратный буст из-за округления не всегда даёт прежние числа | Переводы денег, создание субаккаунта и постановку заданий шлите с заголовком `Idempotency-Key` (1–64 символа): тот же ключ с тем же телом в течение 24 ч вернёт сохранённый ответ без повтора действия; позже тот же ключ — новое действие. Без него не повторяйте такой запрос после таймаута: первый мог выполниться. Ссылка входа в субаккаунт (`POST /subaccounts/{id}/login-link`) даёт вход без пароля на 5 минут, один раз. Не записывайте её в журналы и не открывайте сами: откроете — она погаснет. Ключ API и секрет вебхука не публикуйте в примерах, переписке и журналах. Не обходите лимиты другим ключом и перебором id.