{
  "openapi": "3.1.0",
  "info": {
    "title": "bk-console API",
    "version": "1.0.0",
    "description": "API клиентской панели bk-console.com: проекты и ключи, статистика и баланс, разовые задания с вебхуком, забор заданий с сервера клиента (Источник), субаккаунты реселлера. Вся документация одним файлом — `/llms-full.md`.\n\n**Авторизация.** Заголовок `X-Auth-Token: bk_…` — ключ API аккаунта, выпускается на экране «Профиль» панели. Ключ имеет права своего аккаунта. Заголовок `X-BK` по ключу не нужен. API вызывается с сервера: CORS закрыт, браузер со стороннего сайта запрос не выполнит (preflight `OPTIONS` — 405). Ключ API в код страницы не кладите.\n\n**Ответ.** `{\"ok\": true, \"data\": …}`; список несёт ещё `next_cursor` (null — страниц больше нет). Ошибка — `{\"ok\": false, \"error\": \"текст\"}` с HTTP 4xx или 5xx. Исключения — ответы nginx 413, 502 и 504: у них тело HTML (таблица ниже). Тексты ошибок каждого метода перечислены в его `x-errors` дословно; `<…>` в тексте — подставляемое значение.\n\n**Тело запроса** — объект JSON до 2 МиБ. Неизвестное поле тела — 400 `<поле>: неизвестное поле` у методов, где этот текст есть в `x-errors`; остальные методы неизвестные поля пропускают молча.\n\n**Деньги** — целые копейки (`*_kop`). **Время** — ISO 8601 UTC до секунд, без дробной части: `2026-11-20T07:15:00+00:00`. **Сутки** статистики и даты `date_from`, `date_to` — МСК.\n\n**Лимиты** — запросов в календарную минуту на аккаунт: общий `all` 60 и лимит метода сверх него: `write` 20, `boost` 1, `stats` 12, `tasks` 15, `money` 30, `login_link` 30. Превышение — 429 и заголовок `Retry-After` в секундах.\n\n**Пагинация** — `limit` (1–500, у отчётов 1–100, умолчание 100) и `cursor` из `next_cursor`.\n\n**Повтор запроса** — заголовок `Idempotency-Key` (1–64 символа) у `POST /tasks`, `POST /subaccounts` и переводов: тот же ключ и то же тело — сохранённый ответ без повтора действия. Ключ помнится 24 ч: позже тот же ключ — новое действие.\n\n**Общие ошибки** (у любого метода):\n\n| HTTP | Текст | Что произошло | Что делать |\n|---|---|---|---|\n| 401 | `нужен вход` | нет заголовка `X-Auth-Token` (и нет входа в панель) | передайте ключ |\n| 401 | `ключ API не найден или отозван` | ключ неверный, отозван или не начинается с `bk_` | выпустите новый на экране «Профиль» |\n| 403 | `аккаунт заблокирован: напишите админу в Telegram` | аккаунт ключа заблокирован | напишите админу |\n| 403 | `метод доступен только из панели: войдите на сайт` | метод панели (`/account/keys*`) вызван по ключу | войдите в панель |\n| 400 | `тело — не JSON` | тело не разобралось как JSON | исправьте тело и `Content-Type` |\n| 400 | `тело — не объект JSON` | тело — массив или значение, а не объект | оберните в объект |\n| 400 | `параметр <имя>: <текст FastAPI>` | параметр пути или query не того типа или вне пределов (`id=abc`, `id=0`); текст после двоеточия — на английском | исправьте параметр |\n| 404 | `не найдено` | нет такого пути | сверьте путь с `/openapi.json` |\n| 405 | `метод не поддерживается: сверьте путь и метод с /openapi.json` | путь есть, метод другой | сверьте метод |\n| 429 | `слишком много запросов: лимит <N> в минуту (<лимит>), повторите через <S> с` | лимит исчерпан | ждите `Retry-After` секунд |\n| 500 | `внутренняя ошибка сервера: повторите позже` | необработанный сбой панели | повторите позже; изменяющий запрос без `Idempotency-Key` перед повтором проверьте: действие могло выполниться |\n| 413 | тело HTML от nginx, не JSON | тело запроса больше 2 МиБ | разбейте запрос на части |\n| 502, 504 | тело HTML от nginx, не JSON | панель перезапускается или не ответила за 60 с | повторите позже; действие могло выполниться: проверьте его перед повтором или шлите с `Idempotency-Key` |\n| 307 | пустое тело, заголовок `Location` | путь с `/` на конце: панель перенаправляет на путь без `/` | пишите путь без `/` в конце |\n"
  },
  "servers": [
    {
      "url": "https://bk-console.com/api/v1"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "tags": [
    {
      "name": "account",
      "description": "Аккаунт, ключи API, показатели, баланс, операции"
    },
    {
      "name": "projects",
      "description": "Проекты (сайты) и их ключи, буст, статистика"
    },
    {
      "name": "tasks",
      "description": "Разовые задания: сайт + ключ + регион, один клик или «не найден», вебхук"
    },
    {
      "name": "source",
      "description": "Источник заданий: сервер клиента по API.md (GET на адрес забора, POST на адрес результатов)"
    },
    {
      "name": "subaccounts",
      "description": "Субаккаунты реселлера: переводы, цена клика, ссылка входа"
    }
  ],
  "paths": {
    "/account": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "Аккаунт ключа",
        "description": "**Кто:** все.\n\nАккаунт, с правами которого выполняются запросы: роль, реселлер или субаккаунт, цена клика, баланс, стоп. Проверка ключа и связи — этим методом: он ничего не меняет.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-errors": []
      }
    },
    "/account/keys": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "Ключи API аккаунта",
        "description": "**Кто:** все, только из панели.\n\nНеотозванные ключи аккаунта, новые первыми. Ключ целиком не отдаётся: только `prefix`. По ключу API метод отвечает 403 `метод доступен только из панели: войдите на сайт`.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-errors": [],
        "security": [
          {
            "PanelSession": []
          }
        ]
      },
      "post": {
        "tags": [
          "account"
        ],
        "summary": "Выпустить ключ API",
        "description": "**Кто:** все, только из панели.\n\nКлюч целиком — только в этом ответе: панель хранит его sha256. Неотозванных ключей у аккаунта — до 10. Тело можно не передавать. Неизвестные поля тела пропускаются молча.",
        "responses": {
          "201": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ApiKeyCreated"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«name: до 64 символов»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«ключей уже 10: отзовите ненужный»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 64
                  }
                }
              },
              "example": {
                "name": "сервер интеграции"
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "name: до 64 символов",
            "why": "name не строка или длиннее 64 символов",
            "todo": "сократите имя"
          },
          {
            "status": 409,
            "text": "ключей уже 10: отзовите ненужный",
            "why": "у аккаунта уже 10 неотозванных ключей",
            "todo": "отзовите ненужный ключ: `DELETE /account/keys/{key_id}`"
          }
        ],
        "security": [
          {
            "PanelSession": []
          }
        ]
      }
    },
    "/account/keys/{key_id}": {
      "delete": {
        "tags": [
          "account"
        ],
        "summary": "Отозвать ключ API",
        "description": "**Кто:** все, только из панели.\n\nКлюч перестаёт работать со следующего запроса: тот отвечает 401.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "revoked": {
                          "const": true
                        }
                      },
                      "required": [
                        "revoked"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«ключ не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "key_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9223372036854775807
            }
          }
        ],
        "x-errors": [
          {
            "status": 404,
            "text": "ключ не найден",
            "why": "ключа нет, он чужой или уже отозван",
            "todo": "проверьте id: `GET /account/keys`"
          }
        ],
        "security": [
          {
            "PanelSession": []
          }
        ]
      }
    },
    "/performance": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "Показатели за сутки",
        "description": "**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).\n\nПлан и факт кликов проектов за сутки МСК, счётчики разовых заданий, расход и баланс. Клики приходят в статистику с отставанием около 10 мин. `clicked`, `not_found`, `other` — только по проектам: разовые задания — в `oneoff`.\n\nОхват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Performance"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [],
        "x-errors": [],
        "x-limit": "stats"
      }
    },
    "/balance": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "Баланс",
        "description": "**Кто:** все.\n\nБаланс, цена клика, кредит проверенного клиента, стоп и расход за сутки МСК и за 7 суток.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Balance"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [],
        "x-errors": []
      }
    },
    "/transactions": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "Операции по балансу",
        "description": "**Кто:** все.\n\nСтроки бухгалтерии по id убыванием. Списание за клики проекта — строка на окно 5 мин и проект (`clicks` — кликов в строке). Разовое задание — строка на задание (`oneoff_id`). Даты — сутки МСК, до 93 суток; передана одна дата — вторая берётся по правилу: нет `date_to` — сегодня, нет `date_from` — 93 суток по `date_to`.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Transaction"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "курсор следующей страницы; null — страниц больше нет"
                    }
                  },
                  "required": [
                    "ok",
                    "data",
                    "next_cursor"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«kind: deposit, charge, refund, adjust, transfer или commission»; «date_from: дата ГГГГ-ММ-ДД»; «date_to: дата ГГГГ-ММ-ДД»; «date_from: дата от 2000-01-01 до 2100-12-31»; «date_to: дата от 2000-01-01 до 2100-12-31»; «date_to раньше date_from»; «период больше 93 суток»; «limit: целое 1–500»; «cursor: неверный курсор»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "deposit",
                "charge",
                "refund",
                "adjust",
                "transfer",
                "commission"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/DateFrom"
          },
          {
            "$ref": "#/components/parameters/DateTo"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "kind: deposit, charge, refund, adjust, transfer или commission",
            "why": "kind не из списка",
            "todo": "передайте одно из значений или уберите kind"
          },
          {
            "status": 400,
            "text": "date_from: дата ГГГГ-ММ-ДД",
            "why": "дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля)",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_to: дата ГГГГ-ММ-ДД",
            "why": "то же для date_to",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_from: дата от 2000-01-01 до 2100-12-31",
            "why": "date_from раньше 2000-01-01 или позже 2100-12-31",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to: дата от 2000-01-01 до 2100-12-31",
            "why": "то же для date_to",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to раньше date_from",
            "why": "конец периода раньше начала",
            "todo": "поменяйте даты местами"
          },
          {
            "status": 400,
            "text": "период больше 93 суток",
            "why": "между date_from и date_to больше 93 суток включительно",
            "todo": "разбейте период на части"
          },
          {
            "status": 400,
            "text": "limit: целое 1–500",
            "why": "limit не целое или вне 1–500",
            "todo": "передайте limit от 1 до 500"
          },
          {
            "status": 400,
            "text": "cursor: неверный курсор",
            "why": "cursor не из next_cursor прошлой страницы",
            "todo": "передайте next_cursor прошлого ответа как есть"
          }
        ]
      }
    },
    "/projects": {
      "get": {
        "tags": [
          "projects"
        ],
        "summary": "Список проектов",
        "description": "**Кто:** все.\n\nНескрытые проекты аккаунта по id убыванием.\n\nКлики, «не найден» и позиции клиенту считаются только по домену проекта: у Списка флота, привязанного к проекту целиком, — строки домена проекта (с `www.` и без, без учёта регистра, IDN как punycode), строки других сайтов этого Списка не входят. История — с суток МСК создания Списка во флоте.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Project"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "курсор следующей страницы; null — страниц больше нет"
                    }
                  },
                  "required": [
                    "ok",
                    "data",
                    "next_cursor"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«enabled: true или false»; «limit: целое 1–500»; «cursor: неверный курсор»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "часть домена",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "enabled",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "enabled: true или false",
            "why": "enabled не true, false, 1 или 0",
            "todo": "передайте true или false"
          },
          {
            "status": 400,
            "text": "limit: целое 1–500",
            "why": "limit не целое или вне 1–500",
            "todo": "передайте limit от 1 до 500"
          },
          {
            "status": 400,
            "text": "cursor: неверный курсор",
            "why": "cursor не из next_cursor прошлой страницы",
            "todo": "передайте next_cursor прошлого ответа как есть"
          }
        ]
      },
      "post": {
        "tags": [
          "projects"
        ],
        "summary": "Создать проекты или заменить ключи",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nКак загрузка файла на экране «Проекты». Строки группируются по домену, каждый домен — свой проект. Проект с таким доменом у аккаунта уже есть — его ключи заменяются целиком, скрытый проект снова показывается. Домен сравнивается целиком: `www.example.com` и `example.com` — два разных проекта (предел 1 000 000 в сутки у них общий). Чтобы заменить ключи, передавайте url с тем же хостом, что `domain` проекта. Если в проекте есть ключи другого сайта, ключи не заменяются: `projects[].error` с текстом «в проекте есть строки другого сайта: его правит админ».\n\nТело — `text` (строки `сайт;ключ|бренд1|бренд2;клики[@дни];&lr=регион`) или `keys` (массив KeyIn, 1–50000). `text` берётся, только если `keys` не передан. Ключ без `url` получает домен из поля `domain`; нет и его — строка считается в `bad` без текста ошибки.\n\n`enabled` применяется и к проекту, который уже есть: без поля проект включается (умолчание true). Чтобы заменить ключи выключенного проекта и не включить его, передайте `enabled: false`. Новый проект начинает работу сразу, если `enabled` true и у аккаунта нет стопа. Предел — 1 000 000 кликов в сутки на сайт по всем проектам аккаунта. Ошибка одного домена не роняет запрос: она в `projects[].error`. Строки, которые не разобрал флот, — в `projects[].error_rows`.\n\nТело — до 2 МиБ (предел nginx, больше — 413 с телом HTML): 50 000 ключей в него не помещаются. Ключ обычно занимает 100–300 байт; большую загрузку делите на части.\n\n`limit_day` и `keys` проекта сразу после записи — числа флота вместе с выключенными ключами; сверка раз в 10 мин оставляет только включённые.",
        "responses": {
          "201": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "projects": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ImportResult"
                          }
                        },
                        "bad": {
                          "type": "integer",
                          "description": "строк без домена (не попали ни в один проект)",
                          "example": 0
                        }
                      },
                      "required": [
                        "projects",
                        "bad"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «items[<i>].<поле>: неизвестное поле»; «enabled: true или false»; «note: до 200 символов»; «keys: от 1 до 50000 ключей»; «items[<i>].key: 1–200 символов без ; и |»; «items[<i>].clicks: целое 1–100000»; «items[<i>].every_days: целое 1–365»; «items[<i>].region: номер региона или спинтакс {…} из цифр, { } и |»; «items[<i>].brands: до 20 слов, каждое 1–100 символов без ; и |»; «items[<i>].host_brand: 1–100 символов без ; и |»; «items[<i>].url: адрес страницы сайта без ; | # и пробелов, до 500 символов»; «ни одной строки с доменом: загрузите файл или вставьте строки вида https://сайт.ru;ключ;100;&lr=213»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "домен для keys без url"
                  },
                  "keys": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/KeyIn"
                    },
                    "minItems": 1,
                    "maxItems": 50000
                  },
                  "text": {
                    "type": "string",
                    "description": "строки файла Списка"
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "enabled": {
                    "type": "boolean",
                    "default": true,
                    "description": "true — проект включается, в том числе существующий и скрытый; false — выключается"
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "text": "https://example.com/catalog;купить диван|ikea;70;&lr=213\nexample.com;диван недорого;30@2;&lr=2",
                "note": "Диваны",
                "enabled": true
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: domain, keys, text, note, enabled. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "items[<i>].<поле>: неизвестное поле",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]) поле не из списка: url, key, brands, clicks, every_days, region, host_brand",
            "todo": "исправьте имя поля"
          },
          {
            "status": 400,
            "text": "enabled: true или false",
            "why": "enabled не булево",
            "todo": "передайте true или false"
          },
          {
            "status": 400,
            "text": "note: до 200 символов",
            "why": "note не строка или длиннее 200 символов",
            "todo": "сократите заметку"
          },
          {
            "status": 400,
            "text": "keys: от 1 до 50000 ключей",
            "why": "нет ни `keys`, ни `text` строкой, или в keys не 1–50000 элементов",
            "todo": "передайте keys или text"
          },
          {
            "status": 400,
            "text": "items[<i>].key: 1–200 символов без ; и |",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]): key пуст, длиннее 200 символов, содержит ; | или перевод строки, или элемент — не объект",
            "todo": "исправьте ключ <i> (номер с 0)"
          },
          {
            "status": 400,
            "text": "items[<i>].clicks: целое 1–100000",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]): clicks нет, не целое или вне 1–100000",
            "todo": "передайте лимит в сутки целым числом"
          },
          {
            "status": 400,
            "text": "items[<i>].every_days: целое 1–365",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]): every_days не целое или вне 1–365",
            "todo": "передайте число суток или уберите поле (умолчание 1)"
          },
          {
            "status": 400,
            "text": "items[<i>].region: номер региона или спинтакс {…} из цифр, { } и |",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]): region не число до 8 цифр и не спинтакс вида {213|2}",
            "todo": "передайте номер региона Яндекса (213 — Москва)"
          },
          {
            "status": 400,
            "text": "items[<i>].brands: до 20 слов, каждое 1–100 символов без ; и |",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]): brands не массив строк, больше 20 слов, пустое или длинное слово, слово с ; |",
            "todo": "исправьте массив бренд-слов"
          },
          {
            "status": 400,
            "text": "items[<i>].host_brand: 1–100 символов без ; и |",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]): host_brand длиннее 100 символов или содержит ; |",
            "todo": "исправьте или уберите host_brand"
          },
          {
            "status": 400,
            "text": "items[<i>].url: адрес страницы сайта без ; | # и пробелов, до 500 символов",
            "why": "в элементе keys[<i>] (текст говорит items[<i>]): url длиннее 500 символов или содержит ; | # пробел",
            "todo": "передайте адрес страницы без этих символов"
          },
          {
            "status": 400,
            "text": "ни одной строки с доменом: загрузите файл или вставьте строки вида https://сайт.ru;ключ;100;&lr=213",
            "why": "ни в одной строке не нашёлся домен",
            "todo": "добавьте сайт в строки или поле domain"
          },
          {
            "status": "201, projects[].error",
            "text": "лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт",
            "why": "этот домен не записан: сумма лимитов сайта больше 1 000 000",
            "todo": "уменьшите лимиты ключей этого домена"
          },
          {
            "status": "201, projects[].error",
            "text": "флот не принял проект: напишите админу в Telegram",
            "why": "Пульт флота отказал или не ответил",
            "todo": "повторите запрос: проект с тем же доменом заменит ключи"
          },
          {
            "status": "201, projects[].error",
            "text": "в проекте есть строки другого сайта: его правит админ",
            "why": "проект с этим доменом уже есть. Ключи не заменены.",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram в Telegram"
          }
        ],
        "x-limit": "write"
      }
    },
    "/projects/{id}": {
      "get": {
        "tags": [
          "projects"
        ],
        "summary": "Проект",
        "description": "**Кто:** все.\n\nПроект — только свой и нескрытый.\n\nОхват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Project"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "x-errors": [
          {
            "status": 404,
            "text": "проект не найден",
            "why": "проекта нет, он чужой или скрытый",
            "todo": "проверьте id: `GET /projects`"
          }
        ]
      },
      "patch": {
        "tags": [
          "projects"
        ],
        "summary": "Изменить заметку или бюджет",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nМеняются только переданные поля. Бюджет — на весь срок проекта: `spent_kop ≥ budget_kop` — стоп `budget`. `budget_kop: null` снимает бюджет. Запрос без тела или `{}` — ответ без изменений.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Project"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «note: до 200 символов»; «budget_kop: целое ≥ 0 или null»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 200,
                    "description": "заметка; null или пустая строка — стереть"
                  },
                  "budget_kop": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "note": "Диваны, Москва",
                "budget_kop": 500000
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: note, budget_kop. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "note: до 200 символов",
            "why": "note не строка или длиннее 200 символов",
            "todo": "сократите заметку"
          },
          {
            "status": 400,
            "text": "budget_kop: целое ≥ 0 или null",
            "why": "budget_kop не целое, отрицательное или больше 10^13",
            "todo": "передайте копейки целым числом или null"
          },
          {
            "status": 404,
            "text": "проект не найден",
            "why": "проекта нет, он чужой или скрытый",
            "todo": "проверьте id: `GET /projects`"
          }
        ],
        "x-limit": "write"
      },
      "delete": {
        "tags": [
          "projects"
        ],
        "summary": "Удалить проект",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nКак «Удалить» в панели: проект выключается и скрывается, Список во флоте и статистика остаются. Вернуть проект — `POST /projects` с тем же доменом.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "hidden": {
                          "const": true
                        }
                      },
                      "required": [
                        "hidden"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "x-errors": [
          {
            "status": 404,
            "text": "проект не найден",
            "why": "проекта нет, он чужой или скрытый",
            "todo": "проверьте id: `GET /projects`"
          }
        ],
        "x-limit": "write"
      }
    },
    "/projects/{id}/status": {
      "patch": {
        "tags": [
          "projects"
        ],
        "summary": "Включить или выключить проект",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nВо флот правку пишет воркер за секунды; до записи `pending` у проекта true. Проект со стопом (`stop_reason`) стоит и включённым. `changed` — 1, если состояние поменялось, 0 — уже было таким.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "changed": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "changed"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «enabled: true или false»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "enabled"
                ],
                "additionalProperties": false
              },
              "example": {
                "enabled": false
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: enabled. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "enabled: true или false",
            "why": "enabled нет или не булево",
            "todo": "передайте true или false"
          },
          {
            "status": 404,
            "text": "проект не найден",
            "why": "проекта нет, он чужой или скрытый",
            "todo": "проверьте id: `GET /projects`"
          }
        ],
        "x-limit": "write"
      }
    },
    "/projects/{id}/keys": {
      "get": {
        "tags": [
          "projects"
        ],
        "summary": "Ключи проекта",
        "description": "**Кто:** все.\n\nЗадания Списка проекта из флота со статистикой за сутки МСК. Порядок — как во флоте. `cursor` — смещение (число строкой). `q` — часть ключа без учёта регистра: тогда панель читает все ключи проекта и отбирает сама (на больших проектах медленнее).",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Key"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "курсор следующей страницы; null — страниц больше нет"
                    }
                  },
                  "required": [
                    "ok",
                    "data",
                    "next_cursor"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«limit: целое 1–500»; «cursor: неверный курсор»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден или его правит только админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«у проекта несколько Списков: его правит админ»; «в проекте есть строки другого сайта: его правит админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "«флот не принял проект: напишите админу в Telegram»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "name": "q",
            "in": "query",
            "description": "часть ключа",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "limit: целое 1–500",
            "why": "limit не целое или вне 1–500",
            "todo": "передайте limit от 1 до 500"
          },
          {
            "status": 400,
            "text": "cursor: неверный курсор",
            "why": "cursor не из next_cursor прошлой страницы",
            "todo": "передайте next_cursor прошлого ответа как есть"
          },
          {
            "status": 404,
            "text": "проект не найден или его правит только админ",
            "why": "проекта нет, он чужой, скрыт или в его Списке строки нескольких сайтов",
            "todo": "проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся"
          },
          {
            "status": 409,
            "text": "у проекта несколько Списков: его правит админ",
            "why": "проект собран из нескольких Списков флота",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 502,
            "text": "флот не принял проект: напишите админу в Telegram",
            "why": "Пульт флота не ответил или отказал",
            "todo": "повторите через минуту; не проходит — напишите админу"
          },
          {
            "status": 409,
            "text": "в проекте есть строки другого сайта: его правит админ",
            "why": "в Списке проекта есть строки другого домена",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          }
        ]
      },
      "put": {
        "tags": [
          "projects"
        ],
        "summary": "Добавить и обновить ключи",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nДо 500 ключей за вызов (import merge). Ключ, совпавший по `url`, ключу без учёта регистра и региону, обновляется (лимит, бренды, Хост-бренд) и сохраняет счётчики; новый добавляется; остальные ключи проекта не трогаются. `url` ключа должен быть на домене проекта; без `url` берётся домен проекта. url на `www.`-варианте домена проекта — другой домен: 400 `items[<i>].url: сайт другого домена …`. Предел 1 000 000 кликов в сутки на сайт проверяется до записи; в него входят и выключенные ключи проекта.\n\nПоля вывода `GET /projects/{id}/keys` (`id`, `enabled`, `today`) в `items` не принимаются: 400 `items[<i>].<поле>: неизвестное поле`. Выключение ключей — `PATCH /projects/{id}/keys`.\n\nПосле записи `limit_day` и `keys` проекта — по включённым ключам (N@дни считается как N/дни). Флот не ответил на чтение после записи — до сверки (до 10 мин) стоят числа флота вместе с выключенными ключами.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ImportResult"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «items[<i>].<поле>: неизвестное поле»; «items: от 1 до 500 ключей»; «items[<i>].key: 1–200 символов без ; и |»; «items[<i>].clicks: целое 1–100000»; «items[<i>].every_days: целое 1–365»; «items[<i>].region: номер региона или спинтакс {…} из цифр, { } и |»; «items[<i>].brands: до 20 слов, каждое 1–100 символов без ; и |»; «items[<i>].host_brand: 1–100 символов без ; и |»; «items[<i>].url: адрес страницы сайта без ; | # и пробелов, до 500 символов»; «items[<i>].url: сайт другого домена <домен ключа>, у проекта <домен проекта>»; «лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден или его правит только админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«у проекта несколько Списков: его правит админ»; «в проекте есть строки другого сайта: его правит админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "«флот не принял проект: напишите админу в Telegram»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/KeyIn"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  }
                },
                "required": [
                  "items"
                ],
                "additionalProperties": false
              },
              "example": {
                "items": [
                  {
                    "url": "example.com/catalog",
                    "key": "купить диван",
                    "brands": [
                      "ikea"
                    ],
                    "clicks": 70,
                    "region": "213"
                  },
                  {
                    "key": "диван недорого",
                    "clicks": 30,
                    "every_days": 2,
                    "region": 2
                  }
                ]
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: items. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "items[<i>].<поле>: неизвестное поле",
            "why": "в элементе ключа поле не из списка: url, key, brands, clicks, every_days, region, host_brand; в том числе поля вывода GET /keys: id, enabled, today",
            "todo": "уберите поле; выключение ключей — `PATCH /projects/{id}/keys`"
          },
          {
            "status": 400,
            "text": "items: от 1 до 500 ключей",
            "why": "items нет или в нём не 1–500 элементов",
            "todo": "разбейте на части по 500"
          },
          {
            "status": 404,
            "text": "проект не найден или его правит только админ",
            "why": "проекта нет, он чужой, скрыт или в его Списке строки нескольких сайтов",
            "todo": "проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся"
          },
          {
            "status": 409,
            "text": "у проекта несколько Списков: его правит админ",
            "why": "проект собран из нескольких Списков флота",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 400,
            "text": "items[<i>].key: 1–200 символов без ; и |",
            "why": "в элементе ключа: key пуст, длиннее 200 символов, содержит ; | или перевод строки, или элемент — не объект",
            "todo": "исправьте ключ <i> (номер с 0)"
          },
          {
            "status": 400,
            "text": "items[<i>].clicks: целое 1–100000",
            "why": "в элементе ключа: clicks нет, не целое или вне 1–100000",
            "todo": "передайте лимит в сутки целым числом"
          },
          {
            "status": 400,
            "text": "items[<i>].every_days: целое 1–365",
            "why": "в элементе ключа: every_days не целое или вне 1–365",
            "todo": "передайте число суток или уберите поле (умолчание 1)"
          },
          {
            "status": 400,
            "text": "items[<i>].region: номер региона или спинтакс {…} из цифр, { } и |",
            "why": "в элементе ключа: region не число до 8 цифр и не спинтакс вида {213|2}",
            "todo": "передайте номер региона Яндекса (213 — Москва)"
          },
          {
            "status": 400,
            "text": "items[<i>].brands: до 20 слов, каждое 1–100 символов без ; и |",
            "why": "в элементе ключа: brands не массив строк, больше 20 слов, пустое или длинное слово, слово с ; |",
            "todo": "исправьте массив бренд-слов"
          },
          {
            "status": 400,
            "text": "items[<i>].host_brand: 1–100 символов без ; и |",
            "why": "в элементе ключа: host_brand длиннее 100 символов или содержит ; |",
            "todo": "исправьте или уберите host_brand"
          },
          {
            "status": 400,
            "text": "items[<i>].url: адрес страницы сайта без ; | # и пробелов, до 500 символов",
            "why": "в элементе ключа: url длиннее 500 символов или содержит ; | # пробел",
            "todo": "передайте адрес страницы без этих символов"
          },
          {
            "status": 400,
            "text": "items[<i>].url: сайт другого домена <домен ключа>, у проекта <домен проекта>",
            "why": "url ключа на другом домене; `www.`-вариант домена проекта — тоже другой домен",
            "todo": "другой сайт — отдельный проект: `POST /projects`"
          },
          {
            "status": 409,
            "text": "в проекте есть строки другого сайта: его правит админ",
            "why": "в Списке проекта есть строки другого домена",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 400,
            "text": "лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт",
            "why": "сумма лимитов в сутки этого проекта после записи (N, вместе с выключенными ключами) и `limit_day` других проектов аккаунта с тем же сайтом без `www.`, включая скрытые (M), больше 1 000 000",
            "todo": "уменьшите лимиты ключей."
          },
          {
            "status": 502,
            "text": "флот не принял проект: напишите админу в Telegram",
            "why": "Пульт флота не ответил или отказал",
            "todo": "повторите через минуту; не проходит — напишите админу"
          }
        ],
        "x-limit": "write"
      },
      "patch": {
        "tags": [
          "projects"
        ],
        "summary": "Включить или выключить ключи",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nКлючи по `id` (task_key) включаются или выключаются; счётчики сохраняются. Повтор id в списке считается один раз. `changed` — сколько ключей флот поменял.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "changed": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "changed"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «ids: от 1 до 500 id ключей»; «enabled: true или false»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден или его правит только админ»; «ключ не найден: <id>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«у проекта несколько Списков: его правит админ»; «в проекте есть строки другого сайта: его правит админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "«флот не принял проект: напишите админу в Telegram»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "ids",
                  "enabled"
                ],
                "additionalProperties": false
              },
              "example": {
                "ids": [
                  "3f2a9c0d1e4b5a67"
                ],
                "enabled": false
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: ids, enabled. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "ids: от 1 до 500 id ключей",
            "why": "ids не массив строк или в нём не 1–500 элементов",
            "todo": "передайте id ключей из `GET /projects/{id}/keys`"
          },
          {
            "status": 400,
            "text": "enabled: true или false",
            "why": "enabled нет или не булево",
            "todo": "передайте true или false"
          },
          {
            "status": 404,
            "text": "проект не найден или его правит только админ",
            "why": "проекта нет, он чужой, скрыт или в его Списке строки нескольких сайтов",
            "todo": "проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся"
          },
          {
            "status": 409,
            "text": "у проекта несколько Списков: его правит админ",
            "why": "проект собран из нескольких Списков флота",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 409,
            "text": "в проекте есть строки другого сайта: его правит админ",
            "why": "в Списке проекта есть строки другого домена",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 502,
            "text": "флот не принял проект: напишите админу в Telegram",
            "why": "Пульт флота не ответил или отказал",
            "todo": "повторите через минуту; не проходит — напишите админу"
          },
          {
            "status": 404,
            "text": "ключ не найден: <id>",
            "why": "ключа с таким id нет в проекте (показан первый из ненайденных)",
            "todo": "перечитайте ключи: id меняется вместе с url, ключом и регионом"
          }
        ],
        "x-limit": "write"
      },
      "delete": {
        "tags": [
          "projects"
        ],
        "summary": "Удалить ключи",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nКлючи удаляются из Списка проекта. Тот же ключ, добавленный в этот проект снова, получит прежние счётчики (`id` тот же). Тело обязательно: `{\"ids\": […]}`.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "deleted"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «ids: от 1 до 500 id ключей»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден или его правит только админ»; «ключ не найден: <id>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«у проекта несколько Списков: его правит админ»; «в проекте есть строки другого сайта: его правит админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "«флот не принял проект: напишите админу в Telegram»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  }
                },
                "required": [
                  "ids"
                ],
                "additionalProperties": false
              },
              "example": {
                "ids": [
                  "3f2a9c0d1e4b5a67",
                  "0b1c2d3e4f5a6b7c"
                ]
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: ids. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "ids: от 1 до 500 id ключей",
            "why": "ids не массив строк или в нём не 1–500 элементов",
            "todo": "передайте id ключей"
          },
          {
            "status": 404,
            "text": "проект не найден или его правит только админ",
            "why": "проекта нет, он чужой, скрыт или в его Списке строки нескольких сайтов",
            "todo": "проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся"
          },
          {
            "status": 409,
            "text": "у проекта несколько Списков: его правит админ",
            "why": "проект собран из нескольких Списков флота",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 409,
            "text": "в проекте есть строки другого сайта: его правит админ",
            "why": "в Списке проекта есть строки другого домена",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 502,
            "text": "флот не принял проект: напишите админу в Telegram",
            "why": "Пульт флота не ответил или отказал",
            "todo": "повторите через минуту; не проходит — напишите админу"
          },
          {
            "status": 404,
            "text": "ключ не найден: <id>",
            "why": "ключа с таким id нет в проекте",
            "todo": "перечитайте ключи: `GET /projects/{id}/keys`"
          }
        ],
        "x-limit": "write"
      }
    },
    "/projects/{id}/boost": {
      "post": {
        "tags": [
          "projects"
        ],
        "summary": "Буст: изменить лимиты ключей на процент",
        "description": "**Кто:** все. **Лимит метода:** `boost` (плюс общий `all`).\n\nЛимит каждого ключа × (1 + pct/100), округление, не меньше 1 и не больше 100 000. Предел сайта 1 000 000 в сутки проверяется до записи по включённым ключам, N@дни — как N/дни. Лимит метода — 1 запрос в минуту. `limit_before`, `limit_after` — суммы `clicks` всех ключей, включая выключенные.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "keys": {
                          "type": "integer"
                        },
                        "changed": {
                          "type": "integer"
                        },
                        "limit_before": {
                          "type": "integer"
                        },
                        "limit_after": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "keys",
                        "changed",
                        "limit_before",
                        "limit_after"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «pct: число от −90 до 500»; «лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден или его правит только админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«у проекта несколько Списков: его правит админ»; «в проекте есть строки другого сайта: его правит админ»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "«флот не принял проект: напишите админу в Telegram»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pct": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 500
                  }
                },
                "required": [
                  "pct"
                ],
                "additionalProperties": false
              },
              "example": {
                "pct": 20
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: pct. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "pct: число от −90 до 500",
            "why": "pct нет, не число или вне −90…500",
            "todo": "передайте процент числом"
          },
          {
            "status": 404,
            "text": "проект не найден или его правит только админ",
            "why": "проекта нет, он чужой, скрыт или в его Списке строки нескольких сайтов",
            "todo": "проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся"
          },
          {
            "status": 409,
            "text": "у проекта несколько Списков: его правит админ",
            "why": "проект собран из нескольких Списков флота",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 409,
            "text": "в проекте есть строки другого сайта: его правит админ",
            "why": "в Списке проекта есть строки другого домена",
            "todo": "ключи такого проекта через API не правятся: напишите админу в Telegram"
          },
          {
            "status": 502,
            "text": "флот не принял проект: напишите админу в Telegram",
            "why": "Пульт флота не ответил или отказал",
            "todo": "повторите через минуту; не проходит — напишите админу"
          },
          {
            "status": 400,
            "text": "лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт",
            "why": "сумма лимитов в сутки включённых ключей проекта после буста (N) и `limit_day` других проектов аккаунта с тем же сайтом без `www.`, включая скрытые (M), больше 1 000 000",
            "todo": "уменьшите лимиты ключей."
          }
        ],
        "x-limit": "boost"
      }
    },
    "/projects/{id}/stats": {
      "get": {
        "tags": [
          "projects"
        ],
        "summary": "Статистика проекта по суткам",
        "description": "**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).\n\nСтрока на каждые сутки МСК периода, сутки без данных — нулями. До 93 суток; без дат — 14 суток по сегодня. Клики — с отставанием около 10 мин.\n\nОхват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DayStat"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«date_from: дата ГГГГ-ММ-ДД»; «date_to: дата ГГГГ-ММ-ДД»; «date_from: дата от 2000-01-01 до 2100-12-31»; «date_to: дата от 2000-01-01 до 2100-12-31»; «date_to раньше date_from»; «период больше 93 суток»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/DateFrom"
          },
          {
            "$ref": "#/components/parameters/DateTo"
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "date_from: дата ГГГГ-ММ-ДД",
            "why": "дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля)",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_to: дата ГГГГ-ММ-ДД",
            "why": "то же для date_to",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_from: дата от 2000-01-01 до 2100-12-31",
            "why": "date_from раньше 2000-01-01 или позже 2100-12-31",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to: дата от 2000-01-01 до 2100-12-31",
            "why": "то же для date_to",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to раньше date_from",
            "why": "конец периода раньше начала",
            "todo": "поменяйте даты местами"
          },
          {
            "status": 400,
            "text": "период больше 93 суток",
            "why": "между date_from и date_to больше 93 суток включительно",
            "todo": "разбейте период на части"
          },
          {
            "status": 404,
            "text": "проект не найден",
            "why": "проекта нет, он чужой или скрытый",
            "todo": "проверьте id: `GET /projects`"
          }
        ],
        "x-limit": "stats"
      }
    },
    "/projects/{id}/keys/stats": {
      "get": {
        "tags": [
          "projects"
        ],
        "summary": "Статистика ключей проекта",
        "description": "**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).\n\nСуммы по ключам за период: до 31 суток, без дат — сегодня. Ключ без Сессий в периоде не выводится. `sort=task_key` (умолчание) — порядок по `id` ключа (task_key) возрастанием, курсор — `id`. `sort=not_found` — по `not_found` убыванием, затем по `id`; курсор вида `<not_found>:<id>`. `only=not_found` — только ключи с `not_found` больше 0. Курсор `sort=not_found` держится на сумме `not_found`, а за сегодняшние сутки она растёт между запросами страниц: ключ, у которого `not_found` вырос выше курсора, на следующих страницах не придёт. Полный перебор без пропусков — с `date_to` раньше сегодня или `sort=task_key&only=not_found` с сортировкой у себя.\n\nКакие ключи не находятся в выдаче: `?only=not_found&sort=not_found`. `id` ключа тот же, что у `GET`, `PUT`, `PATCH`, `DELETE /projects/{id}/keys`: найденный ключ правится сразу. Смена страницы, запроса или региона даёт новый ключ с новым `id`.\n\n`url` и `region` — страница и регион ключа из Сессий флота за 40 суток. `null` — страница или регион не заданы, Сессий нет или флот не ответил за 15 с; остальные поля при этом приходят как обычно.\n\nПодсказка `hint_code` и `hint` есть только у ключа с `not_found` больше 0, иначе обе `null`. Подсказка — возможная причина, а не факт:\n\n| `hint_code` | Когда | Текст `hint` |\n|---|---|---|\n| `other_host` | За период в выдаче Сессий с «не найден» был другой поддомен того же сайта, хотя бы в 1/5 таких Сессий. Флот не ответил — не определяется | `В выдаче был <хост> (в <n> из <nf> Сессий с «не найден») — это ваш сайт на другом поддомене: заведите для него отдельный проект` |\n| `seen` | Сегодня (сутки МСК) у ключа была позиция в Поиске без бренда, независимо от `date_from`, `date_to` | `Сегодня сайт был в выдаче (лучшая позиция #<N>), в этих попытках не попал на просмотренные страницы` |\n| `seen` | Сегодня позиции без бренда нет, но были клики: Пульт пишет `best_rank` только по Поиску без бренда, клик через Поиск с брендом позиции не даёт | `Сегодня сайт находили по этой фразе (<n> клик, клика или кликов, позиции без бренда нет), в этих попытках не попал на просмотренные страницы` |\n| `never` | Сегодня не было ни позиции, ни клика | `Сегодня сайт ни разу не найден по этой фразе в этом регионе: проверьте фразу, регион и страницу` |\n\nВетвитесь по `hint_code`: текст `hint` — для человека. `other_host`: ключ проекта не может вести на другой поддомен (`PUT /projects/{id}/keys` отвечает 400), поэтому заведите проект на этом поддомене (`POST /projects`), а старый ключ выключите или удалите (`PATCH`, `DELETE /projects/{id}/keys`).\n\nОхват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/KeyStat"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "курсор следующей страницы; null — страниц больше нет"
                    }
                  },
                  "required": [
                    "ok",
                    "data",
                    "next_cursor"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«date_from: дата ГГГГ-ММ-ДД»; «date_to: дата ГГГГ-ММ-ДД»; «date_from: дата от 2000-01-01 до 2100-12-31»; «date_to: дата от 2000-01-01 до 2100-12-31»; «date_to раньше date_from»; «период больше 31 суток»; «limit: целое 1–500»; «sort: task_key или not_found»; «only: not_found или пусто»; «cursor: неверный курсор»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«проект не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/DateFrom"
          },
          {
            "$ref": "#/components/parameters/DateTo"
          },
          {
            "name": "sort",
            "in": "query",
            "description": "порядок строк: `task_key` — по `id` возрастанием; `not_found` — по `not_found` убыванием, затем по `id`; при `date_to` сегодня перебор страниц может пропустить ключ, чей `not_found` вырос между запросами",
            "schema": {
              "type": "string",
              "enum": [
                "task_key",
                "not_found"
              ],
              "default": "task_key"
            },
            "example": "not_found"
          },
          {
            "name": "only",
            "in": "query",
            "description": "`not_found` — только ключи с `not_found` больше 0; нет или пусто — все ключи",
            "schema": {
              "type": "string",
              "enum": [
                "not_found"
              ]
            },
            "example": "not_found"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "date_from: дата ГГГГ-ММ-ДД",
            "why": "дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля)",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_to: дата ГГГГ-ММ-ДД",
            "why": "то же для date_to",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_from: дата от 2000-01-01 до 2100-12-31",
            "why": "date_from раньше 2000-01-01 или позже 2100-12-31",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to: дата от 2000-01-01 до 2100-12-31",
            "why": "то же для date_to",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to раньше date_from",
            "why": "конец периода раньше начала",
            "todo": "поменяйте даты местами"
          },
          {
            "status": 400,
            "text": "период больше 31 суток",
            "why": "между date_from и date_to больше 31 суток включительно",
            "todo": "разбейте период на части"
          },
          {
            "status": 400,
            "text": "limit: целое 1–500",
            "why": "limit не целое или вне 1–500",
            "todo": "передайте limit от 1 до 500"
          },
          {
            "status": 400,
            "text": "sort: task_key или not_found",
            "why": "sort не task_key и не not_found",
            "todo": "передайте task_key или not_found"
          },
          {
            "status": 400,
            "text": "only: not_found или пусто",
            "why": "only не not_found и не пусто",
            "todo": "передайте not_found или уберите параметр"
          },
          {
            "status": 400,
            "text": "cursor: неверный курсор",
            "why": "cursor не того вида, что next_cursor при этом sort: 16 hex, при sort=not_found — <число>:<16 hex>",
            "todo": "передайте next_cursor прошлого ответа с тем же sort"
          },
          {
            "status": 404,
            "text": "проект не найден",
            "why": "проекта нет, он чужой или скрытый",
            "todo": "проверьте id: `GET /projects`"
          }
        ],
        "x-limit": "stats"
      }
    },
    "/tasks": {
      "post": {
        "tags": [
          "tasks"
        ],
        "summary": "Поставить разовые задания",
        "description": "**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).\n\nДо 500 заданий за вызов. Флот исполняет задание один раз: Целевая Сессия ищет сайт в выдаче Яндекса и кликает. Итог — `done` с `result.outcome` `clicked` (позиция и URL клика) или `not_found` (сайта нет на `serp_pages` страницах). Сессии с ошибкой (капча, сбой, неверный регион) итогом не считаются: задание идёт снова до срока.\n\nВсе задания проверяются до приёма: одна ошибка — 400, не принято ни одно. Порядок проверок: тело и задания (400) → `Idempotency-Key` (400, 409, сохранённый ответ) → разовые задания выключены (503) → деньги (403, 402). Повтор принятого запроса с тем же `Idempotency-Key` получает сохранённый ответ и тогда, когда разовые задания уже выключены. Задание с `id`, который аккаунт уже присылал (через API или панель), не создаётся: в ответе прежнее с `duplicate: true`, деньги на него не проверяются.\n\nДеньги: у непроверенного клиента баланс должен покрыть цену клика × (задания в работе + новые). Проверенный клиент ставит задания без этой проверки. Списание — цена клика аккаунта за `clicked` и за `not_found`.\n\nСрок — 60 мин от приёма. Задание в очереди (`new`) к сроку становится `expired`. Задание во флоте (`running`) ждёт итога ещё запас срока 5 мин: итог в этом окне — `done` со списанием, позже — `expired` без списания. Финальный статус смотрите в `status`, а не по `expires_at`. Итог приходит вебхуком (`PUT /webhook`) и виден в `GET /tasks/{id}`.",
        "responses": {
          "201": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tasks": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "task": {
                                "$ref": "#/components/schemas/Task"
                              },
                              "duplicate": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "task",
                              "duplicate"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "created": {
                          "type": "integer"
                        },
                        "duplicates": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "tasks",
                        "created",
                        "duplicates"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«аккаунт заблокирован: напишите админу в Telegram»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «items[<i>].<поле>: неизвестное поле»; «items: от 1 до 500 заданий»; «items[<i>].id: строка 1–64 символа»; «items: id «<id>» повторяется в запросе»; «items[<i>].site: домен или URL сайта, 3–300 символов»; «items[<i>].key: 1–200 символов без ; и |»; «items[<i>].region: номер региона Яндекса, целое 1–10000000»; «items[<i>].brand: до 100 символов без ; и |»; «items[<i>].brand_mode: none, if_not_found или always»; «items[<i>].brand_mode always: нужен brand»; «items[<i>].serp_pages: целое 1–5»; «Idempotency-Key: 1–64 символа»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "«нет денег на балансе: пополните баланс»; «не хватает денег: <N> заданий в работе и новых × <P> коп. = <X> ₽, на балансе <B> ₽»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«Idempotency-Key уже использован другим методом»; «Idempotency-Key уже использован с другим телом запроса»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "«разовые задания выключены: напишите админу в Telegram»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/TaskIn"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  }
                },
                "required": [
                  "items"
                ],
                "additionalProperties": false
              },
              "example": {
                "items": [
                  {
                    "id": "a1",
                    "site": "example.com",
                    "key": "купить диван москва",
                    "region": 213,
                    "brand": "IKEA",
                    "brand_mode": "if_not_found",
                    "serp_pages": 2
                  },
                  {
                    "id": "a2",
                    "site": "https://example.com/catalog",
                    "key": "диван угловой",
                    "region": "2"
                  }
                ]
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: items. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "items[<i>].<поле>: неизвестное поле",
            "why": "в задании поле не из списка: id, site, key, region, brand, brand_mode, serp_pages",
            "todo": "исправьте имя поля"
          },
          {
            "status": 400,
            "text": "items: от 1 до 500 заданий",
            "why": "items нет или в нём не 1–500 элементов",
            "todo": "разбейте на части по 500"
          },
          {
            "status": 400,
            "text": "items[<i>].id: строка 1–64 символа",
            "why": "id задания не строка или длина не 1–64",
            "todo": "передайте свой id строкой"
          },
          {
            "status": 400,
            "text": "items: id «<id>» повторяется в запросе",
            "why": "два задания в запросе с одним id",
            "todo": "сделайте id уникальными"
          },
          {
            "status": 400,
            "text": "items[<i>].site: домен или URL сайта, 3–300 символов",
            "why": "site пуст, короче 3 или длиннее 300 символов, не домен, путь с ; | или пробелом, или элемент — не объект",
            "todo": "передайте example.com или https://example.com/catalog"
          },
          {
            "status": 400,
            "text": "items[<i>].key: 1–200 символов без ; и |",
            "why": "key пуст, длиннее 200 символов или содержит ; | перевод строки",
            "todo": "исправьте запрос"
          },
          {
            "status": 400,
            "text": "items[<i>].region: номер региона Яндекса, целое 1–10000000",
            "why": "region нет, не целое (или строка цифр) или вне 1–10000000",
            "todo": "передайте номер региона (213 — Москва)"
          },
          {
            "status": 400,
            "text": "items[<i>].brand: до 100 символов без ; и |",
            "why": "brand не строка, длиннее 100 символов или содержит ; |",
            "todo": "исправьте бренд"
          },
          {
            "status": 400,
            "text": "items[<i>].brand_mode: none, if_not_found или always",
            "why": "brand_mode не из списка",
            "todo": "передайте одно из значений или уберите поле"
          },
          {
            "status": 400,
            "text": "items[<i>].brand_mode always: нужен brand",
            "why": "brand_mode always без бренда",
            "todo": "добавьте brand или смените режим"
          },
          {
            "status": 400,
            "text": "items[<i>].serp_pages: целое 1–5",
            "why": "serp_pages не целое или вне 1–5",
            "todo": "передайте 1–5 или уберите поле (умолчание 3)"
          },
          {
            "status": 400,
            "text": "Idempotency-Key: 1–64 символа",
            "why": "заголовок Idempotency-Key пуст или длиннее 64 символов",
            "todo": "передайте ключ 1–64 символа"
          },
          {
            "status": 409,
            "text": "Idempotency-Key уже использован другим методом",
            "why": "тот же Idempotency-Key уже был на другом пути или методе",
            "todo": "для нового действия — новый ключ"
          },
          {
            "status": 409,
            "text": "Idempotency-Key уже использован с другим телом запроса",
            "why": "тот же Idempotency-Key пришёл с другим телом",
            "todo": "для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить)"
          },
          {
            "status": 503,
            "text": "разовые задания выключены: напишите админу в Telegram",
            "why": "разовые задания выключены на всей панели",
            "todo": "дождитесь включения или напишите админу"
          },
          {
            "status": 403,
            "text": "аккаунт заблокирован: напишите админу в Telegram",
            "why": "аккаунт заблокирован",
            "todo": "напишите админу"
          },
          {
            "status": 402,
            "text": "нет денег на балансе: пополните баланс",
            "why": "у аккаунта стоп по деньгам",
            "todo": "пополните баланс"
          },
          {
            "status": 402,
            "text": "не хватает денег: <N> заданий в работе и новых × <P> коп. = <X> ₽, на балансе <B> ₽",
            "why": "непроверенный клиент: баланса не хватит на задания в работе и новые",
            "todo": "пополните баланс или поставьте меньше заданий"
          }
        ],
        "x-limit": "tasks"
      },
      "get": {
        "tags": [
          "tasks"
        ],
        "summary": "Список разовых заданий",
        "description": "**Кто:** все.\n\nЗадания аккаунта по id убыванием, с фильтрами. `created_from`, `created_to` — ISO 8601; без пояса — UTC; границы включительно.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "курсор следующей страницы; null — страниц больше нет"
                    }
                  },
                  "required": [
                    "ok",
                    "data",
                    "next_cursor"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«status: new, running, done, expired, rejected или canceled»; «origin: api, panel или source»; «created_from: время ISO 8601»; «created_to: время ISO 8601»; «limit: целое 1–500»; «cursor: неверный курсор»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "running",
                "done",
                "expired",
                "rejected",
                "canceled"
              ]
            }
          },
          {
            "name": "origin",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "api",
                "panel",
                "source"
              ]
            }
          },
          {
            "name": "created_from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "status: new, running, done, expired, rejected или canceled",
            "why": "status не из списка",
            "todo": "передайте одно из значений"
          },
          {
            "status": 400,
            "text": "origin: api, panel или source",
            "why": "origin не из списка",
            "todo": "передайте одно из значений"
          },
          {
            "status": 400,
            "text": "created_from: время ISO 8601",
            "why": "created_from не разобралось как время или выходит за края при переводе в UTC (0001-01-01T00:00+05:00)",
            "todo": "передайте время вида 2026-11-20T07:00:00Z"
          },
          {
            "status": 400,
            "text": "created_to: время ISO 8601",
            "why": "то же для created_to",
            "todo": "передайте время вида 2026-11-20T08:00:00Z"
          },
          {
            "status": 400,
            "text": "limit: целое 1–500",
            "why": "limit не целое или вне 1–500",
            "todo": "передайте limit от 1 до 500"
          },
          {
            "status": 400,
            "text": "cursor: неверный курсор",
            "why": "cursor не из next_cursor прошлой страницы",
            "todo": "передайте next_cursor прошлого ответа как есть"
          }
        ]
      }
    },
    "/tasks/{id}": {
      "get": {
        "tags": [
          "tasks"
        ],
        "summary": "Разовое задание",
        "description": "**Кто:** все.\n\nЗадание по id панели (`id` из ответа `POST /tasks`, не свой `id`). Только свои. Опрашивайте не чаще раза в минуту: итог приходит и вебхуком.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«задание не найдено»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "x-errors": [
          {
            "status": 404,
            "text": "задание не найдено",
            "why": "задания нет или оно чужое",
            "todo": "проверьте id: это `task.id` из ответа `POST /tasks`"
          }
        ]
      }
    },
    "/tasks/cancel": {
      "post": {
        "tags": [
          "tasks"
        ],
        "summary": "Снять разовые задания",
        "description": "**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).\n\nЗадания в очереди (`new`) по id панели становятся `canceled`, без списания, и во флот не идут. Задание во флоте (`running`) не снимается: Сессия могла уже взять его, оно доходит до итога или срока и списывается как обычно. `new`, которое панель в эту секунду записывает во флот, тоже не снимается. Чужие, несуществующие, финальные и такие id пропускаются молча: `canceled` — сколько снято. Снятое задание уходит вебхуком.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "canceled": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "canceled"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «ids: от 1 до 500 номеров заданий»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  }
                },
                "required": [
                  "ids"
                ],
                "additionalProperties": false
              },
              "example": {
                "ids": [
                  1042,
                  1043
                ]
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: ids. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "ids: от 1 до 500 номеров заданий",
            "why": "ids не массив целых > 0 или в нём не 1–500 элементов",
            "todo": "передайте id панели числами"
          }
        ],
        "x-limit": "tasks"
      }
    },
    "/queue": {
      "get": {
        "tags": [
          "tasks"
        ],
        "summary": "Очередь разовых заданий",
        "description": "**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).\n\nСчётчики аккаунта: в работе сейчас (`new`, `running`) и финальные за сутки МСК. `fleet_max` — сколько разовых заданий всей панели флот исполняет одновременно.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Queue"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«origin: api, panel или source»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "api",
                "panel",
                "source"
              ]
            }
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "origin: api, panel или source",
            "why": "origin не из списка",
            "todo": "передайте одно из значений"
          }
        ],
        "x-limit": "stats"
      },
      "delete": {
        "tags": [
          "tasks"
        ],
        "summary": "Очистить очередь",
        "description": "**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).\n\nСнимает все задания аккаунта в очереди (`new`) с источником `origin` (без него — все), в том числе задания Источника. `status` — только `new`: задания во флоте (`running`) не снимаются, как у `POST /tasks/cancel`. Снятые уходят вебхуком или в Источник с `success: false`.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "canceled": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "canceled"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«status: только new: задание во флоте не снимается»; «origin: api, panel или source»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new"
              ]
            }
          },
          {
            "name": "origin",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "api",
                "panel",
                "source"
              ]
            }
          }
        ],
        "x-errors": [
          {
            "status": 400,
            "text": "status: только new: задание во флоте не снимается",
            "why": "status не new: running снять нельзя",
            "todo": "передайте new или уберите status"
          },
          {
            "status": 400,
            "text": "origin: api, panel или source",
            "why": "origin не из списка",
            "todo": "передайте одно из значений"
          }
        ],
        "x-limit": "tasks"
      }
    },
    "/webhook": {
      "get": {
        "tags": [
          "tasks"
        ],
        "summary": "Настройки вебхука",
        "description": "**Кто:** все.\n\nURL вебхука, есть ли секрет и последняя попытка Доставки. Секрет целиком не отдаётся: только первые 4 символа. Вебхук получает событие `task.finished`, когда задание `api` или `panel` стало `done`, `expired`, `rejected` или `canceled`. Формат — объект WebhookEvent, подпись — раздел «Вебхук» в `/llms-full.md`.\n\nПоле `error` (и `last_delivery.error` в `GET /webhook`):\n\n| Текст | Что произошло | Что делать |\n|---|---|---|\n| `HTTP <код>` | ваш сервер ответил не 2xx | ответьте 2xx; тело ответа панель не читает |\n| `нет ответа за 10 с` | ваш сервер не ответил за 10 с | отвечайте сразу, обработку делайте после ответа |\n| `не удалось подключиться: <текст>` | имя не разрешилось, порт закрыт, ошибка TLS | проверьте адрес и сертификат |\n| `адрес ведёт в частную сеть: <ip>` | адрес разрешается в частную сеть; такая Доставка сразу `failed` | укажите публичный адрес |\n| `неверный адрес вебхука` | адрес не разбирается как URL (сохранён до нынешних проверок адреса); такая Доставка сразу `failed` | задайте адрес заново: `PUT /webhook` |",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-errors": []
      },
      "put": {
        "tags": [
          "tasks"
        ],
        "summary": "Задать URL вебхука",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\n`url: null` выключает вебхук, секрет остаётся. Первый URL создаёт секрет, но не показывает его: получите его `POST /webhook/secret`. Адрес, имя которого пока не разрешается, принимается: ошибку покажут попытки Доставки. Доставка идёт на URL, который был задан в момент итога задания.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «url: адрес http или https до 500 символов»; «url: адрес ведёт в частную сеть»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500
                  }
                },
                "required": [
                  "url"
                ],
                "additionalProperties": false
              },
              "example": {
                "url": "https://example.com/bk-hook"
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: url. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля или уберите его"
          },
          {
            "status": 400,
            "text": "url: адрес http или https до 500 символов",
            "why": "url нет в теле, не строка, не http(s), без хоста, с логином и паролем, с пробелом или управляющим символом, с портом вне 1–65535, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов",
            "todo": "передайте https://ваш-сервер/путь"
          },
          {
            "status": 400,
            "text": "url: адрес ведёт в частную сеть",
            "why": "хост разрешается в частную сеть или loopback",
            "todo": "укажите публичный адрес"
          }
        ],
        "x-limit": "write"
      }
    },
    "/webhook/secret": {
      "post": {
        "tags": [
          "tasks"
        ],
        "summary": "Сменить секрет вебхука",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nНовый секрет — 64 hex. Действует сразу, прежний — нет: Доставки после ответа подписываются новым. Секрет показывается только в этом ответе: сохраните его. Тело не нужно.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "secret": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "secret"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«вебхук не задан: PUT /webhook»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-errors": [
          {
            "status": 409,
            "text": "вебхук не задан: PUT /webhook",
            "why": "у аккаунта нет URL вебхука",
            "todo": "сначала задайте URL: `PUT /webhook`"
          }
        ],
        "x-limit": "write"
      }
    },
    "/webhook/test": {
      "post": {
        "tags": [
          "tasks"
        ],
        "summary": "Проверить вебхук",
        "description": "**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).\n\nОдна попытка события `ping` (`task: null`) с подписью, без повторов. Ответ — итог попытки; она же видна в `last_delivery`. Тело не нужно. Из панели (вход по cookie) проверка тоже считается в лимит `tasks`: 15 в минуту; превышение — 429.\n\nПоле `error` (и `last_delivery.error` в `GET /webhook`):\n\n| Текст | Что произошло | Что делать |\n|---|---|---|\n| `HTTP <код>` | ваш сервер ответил не 2xx | ответьте 2xx; тело ответа панель не читает |\n| `нет ответа за 10 с` | ваш сервер не ответил за 10 с | отвечайте сразу, обработку делайте после ответа |\n| `не удалось подключиться: <текст>` | имя не разрешилось, порт закрыт, ошибка TLS | проверьте адрес и сертификат |\n| `адрес ведёт в частную сеть: <ip>` | адрес разрешается в частную сеть; такая Доставка сразу `failed` | укажите публичный адрес |\n| `неверный адрес вебхука` | адрес не разбирается как URL (сохранён до нынешних проверок адреса); такая Доставка сразу `failed` | задайте адрес заново: `PUT /webhook` |",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "type": "boolean",
                          "description": "ответ 2xx"
                        },
                        "http_status": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "ok",
                        "http_status",
                        "error"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«вебхук не задан: PUT /webhook»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-errors": [
          {
            "status": 409,
            "text": "вебхук не задан: PUT /webhook",
            "why": "у аккаунта нет URL вебхука",
            "todo": "сначала задайте URL: `PUT /webhook`"
          }
        ],
        "x-limit": "tasks"
      }
    },
    "/source": {
      "get": {
        "tags": [
          "source"
        ],
        "summary": "Источник заданий",
        "description": "**Кто:** все.\n\nИсточник — сервер клиента по протоколу API.md. Панель сама берёт с него задания запросом `GET` ровно на `task_url` и шлёт итог `POST` ровно на `result_url`: к адресам ничего не дописывается. `GET /task` и `POST /result` в текстах ниже — названия методов API.md, а не путь запроса. `data: null` — Источник не задан.\n\nИтог задания на адрес в частной сети или на неверный адрес не повторяется: сразу попадает в `results_failed`.\n\nПоле `last_error` Источника. Текст остаётся и после восстановления: сравнивайте `last_error_at` с `last_ok_at`.\n\n| Текст | `state` | Что произошло | Что делать |\n|---|---|---|---|\n| `сервер клиента отказал в доступе: HTTP <401 или 403> на GET /task — проверьте заголовок авторизации` | `auth` | сервер отказал; забор выключен (`enabled: false`) | исправьте `auth_header`, `auth_value` и включите: `PUT /source` с `enabled: true` |\n| `HTTP 404 на GET /task: проверьте адрес` | `error` | по адресу `task_url` ничего нет | исправьте `task_url`: запрос идёт ровно на него |\n| `HTTP <код> на GET /task` | `error` | сервер ответил не 200 и не 204 | исправьте сервер; повтор — с паузой 15, 30, 60 … до 600 с |\n| `ответ GET /task — не JSON-объект` | `error` | тело не JSON-объект или длиннее 64 КБ | отдавайте одно задание объектом JSON |\n| `ответ GET /task без task_id: задание пропущено` | `error` | в ответе нет `task_id` строкой или целым | добавьте `task_id` |\n| `ответ GET /task: task_id длиннее 500 символов, задание пропущено` | `error` | `task_id` строкой длиннее 500 символов: задание не берётся | давайте `task_id` до 64 символов |\n| `нет ответа за 10 с на GET /task` | `error` | сервер не ответил за 10 с | ускорьте ответ |\n| `не удалось подключиться: <текст>` | `error` | имя не разрешилось, порт закрыт, ошибка TLS | проверьте адрес и сертификат |\n| `адрес ведёт в частную сеть: <ip>` | `error` | адрес разрешается в частную сеть; забор выключен | укажите публичный адрес и включите забор |\n| `неверный адрес` | `error` | адрес Источника не разбирается как URL (сохранён до нынешних проверок адреса); забор выключен | задайте адрес заново и включите: `PUT /source` |\n| `разовые задания выключены админом` | `paused` | запросов нет, проверка раз в 60 с | Норма: забор продолжится сам |\n| `нет денег на балансе: забор на паузе` | `paused` | у аккаунта стоп: нет денег или аккаунт заблокирован | пополните баланс: забор продолжится сам |\n| `не хватает денег: <N> заданий в работе и новых × <P> коп. = <X> ₽, на балансе <B> ₽` | `paused` | непроверенный клиент: баланса не хватит ещё на одно задание | пополните баланс |\n| `суточный потолок <N> заданий: забор продолжится в 00:00 МСК` | `paused` | за сутки МСК взято столько, сколько разрешает потолок | Норма. Поднять — свой `day_limit` или потолок панели |",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "anyOf": [
                        {
                          "$ref": "#/components/schemas/Source"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [],
        "x-errors": []
      },
      "put": {
        "tags": [
          "source"
        ],
        "summary": "Задать Источник заданий",
        "description": "**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).\n\nСоздаёт или меняет свой Источник.\n\nАдреса — два полных: `task_url` (забор, `GET`) и `result_url` (итог, `POST`). Панель шлёт запрос ровно на них, ничего не дописывая; адреса могут быть на разных хостах, параметры после `?` разрешены. Оба обязательны.\n\nПрежнее поле `url` (база сервера) принимается вместо двух адресов: панель запишет `task_url` = `<url>/task`, `result_url` = `<url>/result`. `url` вместе с `task_url` или `result_url` — 400. В ответе `url` — основа, если адреса ровно `<основа>/task` и `<основа>/result`, иначе `null`.\n\n`auth_header`, `auth_value`, `day_limit` не переданы — остаются прежними; `null` — очищает. Включение, смена любого из двух адресов или авторизации сбрасывают ошибки: забор начинается сразу.\n\nЗадания Источника исполняются как разовые задания аккаунта и списываются так же. В работе одновременно — не больше `inflight_max` (старт 200), за сутки МСК — не больше меньшего из `day_max` и своего `day_limit`. Задание с `task_id`, который Источник уже отдавал, заново не исполняется: прежний итог уходит на `result_url` ещё раз.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Source"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«<поле>: неизвестное поле»; «url: нельзя вместе с task_url и result_url»; «task_url: обязательно»; «result_url: обязательно»; «task_url: адрес http или https до 500 символов, без логина и пароля и без #»; «result_url: адрес http или https до 500 символов, без логина и пароля и без #»; «url: адрес http или https до 493 символов, без логина и пароля»; «auth_header: латиница, цифры и -, до 64 символов»; «auth_value: до 1000 символов»; «auth_value: только печатные символы ASCII»; «day_limit: целое ≥ 0 или null»; «enabled: true или false»; «task_url: адрес ведёт в частную сеть»; «result_url: адрес ведёт в частную сеть»; «url: адрес ведёт в частную сеть»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "«разовые задания выключены: напишите админу в Telegram»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SourceIn"
              },
              "example": {
                "task_url": "https://tasks.example.com/api/task",
                "result_url": "https://results.example.com/api/result?token=abc",
                "auth_header": "X-Api-Key",
                "auth_value": "secret-value",
                "day_limit": 5000,
                "enabled": true
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 400,
            "text": "<поле>: неизвестное поле",
            "why": "в теле поле не из списка: url, task_url, result_url, auth_header, auth_value, day_limit, enabled. Из нескольких называется первое по алфавиту",
            "todo": "исправьте имя поля: опечатка в day_limit иначе оставила бы забор без своего потолка"
          },
          {
            "status": 400,
            "text": "url: нельзя вместе с task_url и result_url",
            "why": "в теле `url` и хотя бы один из `task_url`, `result_url` не null: неясно, какой адрес имелся в виду",
            "todo": "передайте либо `task_url` и `result_url`, либо только `url`"
          },
          {
            "status": 400,
            "text": "task_url: обязательно",
            "why": "нет ни `url`, ни `task_url` (или он null)",
            "todo": "передайте оба адреса: `task_url` и `result_url`"
          },
          {
            "status": 400,
            "text": "result_url: обязательно",
            "why": "нет ни `url`, ни `result_url` (или он null)",
            "todo": "передайте оба адреса: `task_url` и `result_url`"
          },
          {
            "status": 400,
            "text": "task_url: адрес http или https до 500 символов, без логина и пароля и без #",
            "why": "task_url не строка, не http(s), без хоста, с логином или паролем, с `#`, с пробелом или управляющим символом, с портом 0 или неверным, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов. Параметры после `?` разрешены",
            "todo": "передайте полный адрес забора: https://host[:порт]/путь[?параметры]"
          },
          {
            "status": 400,
            "text": "result_url: адрес http или https до 500 символов, без логина и пароля и без #",
            "why": "result_url не строка, не http(s), без хоста, с логином или паролем, с `#`, с пробелом или управляющим символом, с портом 0 или неверным, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов. Параметры после `?` разрешены",
            "todo": "передайте полный адрес результатов: https://host[:порт]/путь[?параметры]"
          },
          {
            "status": 400,
            "text": "url: адрес http или https до 493 символов, без логина и пароля",
            "why": "url не строка, не http(s), без хоста, с логином или паролем, с `?` или `#` (даже пустыми в конце), с пробелом или управляющим символом, с портом 0 или неверным, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов или длиннее 493 без `/` в конце (493 = 500 − длина `/result`)",
            "todo": "передайте базу сервера https://host[:порт][/путь] или перейдите на `task_url` и `result_url`"
          },
          {
            "status": 400,
            "text": "auth_header: латиница, цифры и -, до 64 символов",
            "why": "имя заголовка с другими символами или длиннее 64",
            "todo": "передайте имя вида X-Api-Key"
          },
          {
            "status": 400,
            "text": "auth_value: до 1000 символов",
            "why": "auth_value не строка или длиннее 1000 символов",
            "todo": "сократите значение"
          },
          {
            "status": 400,
            "text": "auth_value: только печатные символы ASCII",
            "why": "в значении перевод строки или не-ASCII",
            "todo": "передайте значение из печатных ASCII"
          },
          {
            "status": 400,
            "text": "day_limit: целое ≥ 0 или null",
            "why": "day_limit не целое, отрицательное или больше 2147483647",
            "todo": "передайте число или null"
          },
          {
            "status": 400,
            "text": "enabled: true или false",
            "why": "enabled нет или не булево",
            "todo": "передайте true или false"
          },
          {
            "status": 503,
            "text": "разовые задания выключены: напишите админу в Telegram",
            "why": "разовые задания выключены на всей панели",
            "todo": "дождитесь включения или напишите админу"
          },
          {
            "status": 400,
            "text": "task_url: адрес ведёт в частную сеть",
            "why": "хост `task_url` разрешается в частную сеть или loopback",
            "todo": "укажите публичный адрес"
          },
          {
            "status": 400,
            "text": "result_url: адрес ведёт в частную сеть",
            "why": "хост `result_url` разрешается в частную сеть или loopback",
            "todo": "укажите публичный адрес"
          },
          {
            "status": 400,
            "text": "url: адрес ведёт в частную сеть",
            "why": "передан `url`: хост разрешается в частную сеть или loopback",
            "todo": "укажите публичный адрес"
          }
        ],
        "x-limit": "write"
      }
    },
    "/subaccounts": {
      "get": {
        "tags": [
          "subaccounts"
        ],
        "summary": "Субаккаунты",
        "description": "**Кто:** реселлер.\n\nСубаккаунты по id возрастанием. Реселлер видит своих. `q` — часть логина, Telegram или метки (до 100 символов).",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Subaccount"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "курсор следующей страницы; null — страниц больше нет"
                    }
                  },
                  "required": [
                    "ok",
                    "data",
                    "next_cursor"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«субаккаунт не может заводить субаккаунты»; «субаккаунты выключены: напишите админу в Telegram»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«limit: целое 1–500»; «cursor: неверный курсор»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "x-errors": [
          {
            "status": 403,
            "text": "субаккаунт не может заводить субаккаунты",
            "why": "метод вызвал субаккаунт",
            "todo": "методы субаккаунтов — только у реселлера"
          },
          {
            "status": 403,
            "text": "субаккаунты выключены: напишите админу в Telegram",
            "why": "аккаунт не реселлер",
            "todo": "попросите админа включить субаккаунты"
          },
          {
            "status": 400,
            "text": "limit: целое 1–500",
            "why": "limit не целое или вне 1–500",
            "todo": "передайте limit от 1 до 500"
          },
          {
            "status": 400,
            "text": "cursor: неверный курсор",
            "why": "cursor не из next_cursor прошлой страницы",
            "todo": "передайте next_cursor прошлого ответа как есть"
          }
        ]
      },
      "post": {
        "tags": [
          "subaccounts"
        ],
        "summary": "Создать субаккаунт",
        "description": "**Кто:** реселлер. **Лимит метода:** `write` (плюс общий `all`).\n\nСубаккаунт входит в панель своим логином и видит её как обычный клиент. Пароль не передан — генерируется и возвращается один раз в `password`. Баланс нового субаккаунта — 0: переведите ему деньги (`POST /subaccounts/{id}/transfer`). Цена клика не передана — цена реселлера. Неизвестные поля тела пропускаются молча.",
        "responses": {
          "201": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "subaccount": {
                          "$ref": "#/components/schemas/Subaccount"
                        },
                        "password": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "subaccount",
                        "password"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«субаккаунт не может заводить субаккаунты»; «субаккаунты выключены: напишите админу в Telegram»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«логин: 3–32 символа, латиница, цифры, _ . -»; «пароль: от 8 символов»; «Telegram: логин вида @name, 5–32 символа»; «price_kop: целое <P>–100000: не ниже вашей цены клика»; «label: до 100 символов»; «Idempotency-Key: 1–64 символа»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«Idempotency-Key уже использован другим методом»; «Idempotency-Key уже использован с другим телом запроса»; «такой логин уже есть»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubaccountIn"
              },
              "example": {
                "login": "client1",
                "price_kop": 15,
                "label": "Иванов, мебель"
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 403,
            "text": "субаккаунт не может заводить субаккаунты",
            "why": "метод вызвал субаккаунт",
            "todo": "методы субаккаунтов — только у реселлера"
          },
          {
            "status": 403,
            "text": "субаккаунты выключены: напишите админу в Telegram",
            "why": "аккаунт не реселлер",
            "todo": "попросите админа включить субаккаунты"
          },
          {
            "status": 400,
            "text": "логин: 3–32 символа, латиница, цифры, _ . -",
            "why": "login не подходит",
            "todo": "исправьте логин"
          },
          {
            "status": 400,
            "text": "пароль: от 8 символов",
            "why": "password не строка или длина не 8–128",
            "todo": "передайте 8–128 символов или не передавайте"
          },
          {
            "status": 400,
            "text": "Telegram: логин вида @name, 5–32 символа",
            "why": "telegram не похож на логин Telegram",
            "todo": "передайте @name или уберите поле"
          },
          {
            "status": 400,
            "text": "price_kop: целое <P>–100000: не ниже вашей цены клика",
            "why": "цена клика не целое, ниже вашей цены P или больше 100000",
            "todo": "передайте цену не ниже своей"
          },
          {
            "status": 400,
            "text": "label: до 100 символов",
            "why": "label не строка или длиннее 100 символов",
            "todo": "сократите метку"
          },
          {
            "status": 400,
            "text": "Idempotency-Key: 1–64 символа",
            "why": "заголовок Idempotency-Key пуст или длиннее 64 символов",
            "todo": "передайте ключ 1–64 символа"
          },
          {
            "status": 409,
            "text": "Idempotency-Key уже использован другим методом",
            "why": "тот же Idempotency-Key уже был на другом пути или методе",
            "todo": "для нового действия — новый ключ"
          },
          {
            "status": 409,
            "text": "Idempotency-Key уже использован с другим телом запроса",
            "why": "тот же Idempotency-Key пришёл с другим телом",
            "todo": "для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить)"
          },
          {
            "status": 409,
            "text": "такой логин уже есть",
            "why": "логин занят (без учёта регистра)",
            "todo": "выберите другой логин"
          }
        ],
        "x-limit": "write"
      }
    },
    "/subaccounts/{id}": {
      "get": {
        "tags": [
          "subaccounts"
        ],
        "summary": "Субаккаунт",
        "description": "**Кто:** реселлер.\n\nРеселлер — только свой субаккаунт.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Subaccount"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«субаккаунт не может заводить субаккаунты»; «субаккаунты выключены: напишите админу в Telegram»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«субаккаунт не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "x-errors": [
          {
            "status": 403,
            "text": "субаккаунт не может заводить субаккаунты",
            "why": "метод вызвал субаккаунт",
            "todo": "методы субаккаунтов — только у реселлера"
          },
          {
            "status": 403,
            "text": "субаккаунты выключены: напишите админу в Telegram",
            "why": "аккаунт не реселлер",
            "todo": "попросите админа включить субаккаунты"
          },
          {
            "status": 404,
            "text": "субаккаунт не найден",
            "why": "субаккаунта нет или он чужой",
            "todo": "проверьте id: `GET /subaccounts`"
          }
        ]
      },
      "patch": {
        "tags": [
          "subaccounts"
        ],
        "summary": "Изменить субаккаунт",
        "description": "**Кто:** реселлер. **Лимит метода:** `write` (плюс общий `all`).\n\nЦена клика, метка, блок; меняются только переданные поля, пустой объект `{}` — ответ без изменений (запрос совсем без тела — 400 `тело — не JSON`). Неизвестные поля тела пропускаются молча. Блок закрывает входы субаккаунта и непогашенные ссылки входа, проекты встают на стоп `blocked`. Реселлер ставит цену не ниже своей.\n\nБлок, поставленный админом (`admin_blocked: true`), реселлер не снимает: `status: active` даёт 403.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Subaccount"
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«субаккаунт не может заводить субаккаунты»; «субаккаунты выключены: напишите админу в Telegram»; «субаккаунт заблокирован админом: снять блок может только админ»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«price_kop: целое <P>–100000: не ниже вашей цены клика»; «label: до 100 символов»; «status: active или blocked»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«субаккаунт не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "price_kop": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100000
                  },
                  "label": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "blocked"
                    ]
                  }
                }
              },
              "example": {
                "price_kop": 20,
                "status": "blocked"
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 403,
            "text": "субаккаунт не может заводить субаккаунты",
            "why": "метод вызвал субаккаунт",
            "todo": "методы субаккаунтов — только у реселлера"
          },
          {
            "status": 403,
            "text": "субаккаунты выключены: напишите админу в Telegram",
            "why": "аккаунт не реселлер",
            "todo": "попросите админа включить субаккаунты"
          },
          {
            "status": 400,
            "text": "price_kop: целое <P>–100000: не ниже вашей цены клика",
            "why": "реселлер: цена ниже его цены P, не целое или больше 100000",
            "todo": "передайте цену не ниже своей"
          },
          {
            "status": 400,
            "text": "label: до 100 символов",
            "why": "label не строка или длиннее 100 символов",
            "todo": "сократите метку"
          },
          {
            "status": 400,
            "text": "status: active или blocked",
            "why": "status не из списка",
            "todo": "передайте active или blocked"
          },
          {
            "status": 404,
            "text": "субаккаунт не найден",
            "why": "субаккаунта нет или он чужой",
            "todo": "проверьте id: `GET /subaccounts`"
          },
          {
            "status": 403,
            "text": "субаккаунт заблокирован админом: снять блок может только админ",
            "why": "реселлер передал status active, а блок поставил админ (admin_blocked: true)",
            "todo": "напишите админу в Telegram"
          }
        ],
        "x-limit": "write"
      }
    },
    "/subaccounts/{id}/transfer": {
      "post": {
        "tags": [
          "subaccounts"
        ],
        "summary": "Перевести деньги субаккаунту или вернуть",
        "description": "**Кто:** реселлер. **Лимит метода:** `money` (плюс общий `all`).\n\n`to_sub` — с баланса реселлера на баланс субаккаунта, `from_sub` — обратно. В минус перевод не уводит: кредит проверенного клиента на переводы не действует. У непроверенного субаккаунта `from_sub` не забирает резерв под его разовые задания в работе: (`new` + `running`) × его цена клика. У непроверенного реселлера `to_sub` так же не переводит резерв под его собственные разовые задания в работе. Две строки `transfer` (у отправителя и получателя) в одной транзакции. `comment` длиннее 500 символов обрезается. Шлите с `Idempotency-Key`. Неизвестные поля тела пропускаются молча.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "parent_balance_kop": {
                          "type": "integer"
                        },
                        "sub_balance_kop": {
                          "type": "integer"
                        },
                        "transaction_ids": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        }
                      },
                      "required": [
                        "parent_balance_kop",
                        "sub_balance_kop",
                        "transaction_ids"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«субаккаунт не может заводить субаккаунты»; «субаккаунты выключены: напишите админу в Telegram»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«amount_kop: целое 1–10000000000»; «direction: to_sub или from_sub»; «Idempotency-Key: 1–64 символа»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "«недостаточно денег на балансе: <B> ₽»; «недостаточно денег на балансе: свободно <F> ₽, <R> ₽ в резерве под разовые задания в работе»; «недостаточно денег у субаккаунта: <B> ₽»; «недостаточно денег у субаккаунта: свободно <F> ₽, <R> ₽ в резерве под разовые задания в работе»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«субаккаунт не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«Idempotency-Key уже использован другим методом»; «Idempotency-Key уже использован с другим телом запроса»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount_kop": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000000000
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "to_sub",
                      "from_sub"
                    ]
                  },
                  "comment": {
                    "type": "string",
                    "description": "заметка: попадает только в строку реселлера, субаккаунт её не видит",
                    "maxLength": 500
                  }
                },
                "required": [
                  "amount_kop",
                  "direction"
                ]
              },
              "example": {
                "amount_kop": 100000,
                "direction": "to_sub",
                "comment": "аванс за ноябрь"
              }
            }
          }
        },
        "x-errors": [
          {
            "status": 403,
            "text": "субаккаунт не может заводить субаккаунты",
            "why": "метод вызвал субаккаунт",
            "todo": "методы субаккаунтов — только у реселлера"
          },
          {
            "status": 403,
            "text": "субаккаунты выключены: напишите админу в Telegram",
            "why": "аккаунт не реселлер",
            "todo": "попросите админа включить субаккаунты"
          },
          {
            "status": 400,
            "text": "amount_kop: целое 1–10000000000",
            "why": "сумма не целое или вне 1…10^10 копеек",
            "todo": "передайте копейки целым числом"
          },
          {
            "status": 400,
            "text": "direction: to_sub или from_sub",
            "why": "direction не из списка",
            "todo": "передайте to_sub или from_sub"
          },
          {
            "status": 400,
            "text": "Idempotency-Key: 1–64 символа",
            "why": "заголовок Idempotency-Key пуст или длиннее 64 символов",
            "todo": "передайте ключ 1–64 символа"
          },
          {
            "status": 409,
            "text": "Idempotency-Key уже использован другим методом",
            "why": "тот же Idempotency-Key уже был на другом пути или методе",
            "todo": "для нового действия — новый ключ"
          },
          {
            "status": 409,
            "text": "Idempotency-Key уже использован с другим телом запроса",
            "why": "тот же Idempotency-Key пришёл с другим телом",
            "todo": "для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить)"
          },
          {
            "status": 404,
            "text": "субаккаунт не найден",
            "why": "субаккаунта нет или он чужой",
            "todo": "проверьте id: `GET /subaccounts`"
          },
          {
            "status": 402,
            "text": "недостаточно денег на балансе: <B> ₽",
            "why": "to_sub: у реселлера меньше суммы перевода (B — его баланс)",
            "todo": "пополните баланс или переведите меньше"
          },
          {
            "status": 402,
            "text": "недостаточно денег на балансе: свободно <F> ₽, <R> ₽ в резерве под разовые задания в работе",
            "why": "to_sub у непроверенного реселлера: баланс минус резерв R под его разовые задания в работе меньше суммы",
            "todo": "переведите не больше F или дождитесь итога заданий"
          },
          {
            "status": 402,
            "text": "недостаточно денег у субаккаунта: <B> ₽",
            "why": "from_sub: у субаккаунта меньше суммы",
            "todo": "верните не больше B"
          },
          {
            "status": 402,
            "text": "недостаточно денег у субаккаунта: свободно <F> ₽, <R> ₽ в резерве под разовые задания в работе",
            "why": "from_sub у непроверенного субаккаунта: баланс минус резерв R меньше суммы",
            "todo": "верните не больше F или дождитесь итога заданий"
          }
        ],
        "x-limit": "money"
      }
    },
    "/subaccounts/{id}/login-link": {
      "post": {
        "tags": [
          "subaccounts"
        ],
        "summary": "Ссылка входа в субаккаунт",
        "description": "**Кто:** реселлер. **Лимит метода:** `login_link` (плюс общий `all`).\n\nОдноразовая ссылка входа без пароля, живёт 5 минут. Открытая один раз — гаснет. Отдайте её клиенту, сами не открывайте и не пишите в журналы. Ссылка ведёт на домен, с которого пришёл запрос. Тело не нужно.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "expires_in": {
                          "const": 300
                        }
                      },
                      "required": [
                        "url",
                        "expires_in"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ok",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«субаккаунт не может заводить субаккаунты»; «субаккаунты выключены: напишите админу в Telegram»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "«субаккаунт не найден»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "«субаккаунт заблокирован»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "x-errors": [
          {
            "status": 403,
            "text": "субаккаунт не может заводить субаккаунты",
            "why": "метод вызвал субаккаунт",
            "todo": "методы субаккаунтов — только у реселлера"
          },
          {
            "status": 403,
            "text": "субаккаунты выключены: напишите админу в Telegram",
            "why": "аккаунт не реселлер",
            "todo": "попросите админа включить субаккаунты"
          },
          {
            "status": 404,
            "text": "субаккаунт не найден",
            "why": "субаккаунта нет или он чужой",
            "todo": "проверьте id: `GET /subaccounts`"
          },
          {
            "status": 409,
            "text": "субаккаунт заблокирован",
            "why": "субаккаунт в статусе blocked",
            "todo": "снимите блок: `PATCH /subaccounts/{id}`"
          }
        ],
        "x-limit": "login_link"
      }
    },
    "/subaccounts/report": {
      "get": {
        "tags": [
          "subaccounts"
        ],
        "summary": "Отчёт по субаккаунтам",
        "description": "**Кто:** реселлер. **Лимит метода:** `stats` (плюс общий `all`).\n\nСтрока на субаккаунт за период: сутки МСК, до 93. Без `date_from` — 30 суток по `date_to`, без `date_to` — по сегодня. Субаккаунт без движения денег в периоде и с нулём на начало не выводится. Возвраты (`refund`) отдельной колонкой не показаны: при них `closing_kop − opening_kop` не равно сумме колонок.",
        "responses": {
          "200": {
            "description": "ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SummaryRow"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "курсор следующей страницы; null — страниц больше нет"
                    }
                  },
                  "required": [
                    "ok",
                    "data",
                    "next_cursor"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "«субаккаунт не может заводить субаккаунты»; «субаккаунты выключены: напишите админу в Telegram»; общие: «аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "400": {
            "description": "«date_from: дата ГГГГ-ММ-ДД»; «date_to: дата ГГГГ-ММ-ДД»; «date_from: дата от 2000-01-01 до 2100-12-31»; «date_to: дата от 2000-01-01 до 2100-12-31»; «date_to раньше date_from»; «период больше 93 суток»; «limit: целое 1–100»; «cursor: неверный курсор»; общие: «тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>»",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/DateFrom"
          },
          {
            "$ref": "#/components/parameters/DateTo"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          }
        ],
        "x-errors": [
          {
            "status": 403,
            "text": "субаккаунт не может заводить субаккаунты",
            "why": "метод вызвал субаккаунт",
            "todo": "методы субаккаунтов — только у реселлера"
          },
          {
            "status": 403,
            "text": "субаккаунты выключены: напишите админу в Telegram",
            "why": "аккаунт не реселлер",
            "todo": "попросите админа включить субаккаунты"
          },
          {
            "status": 400,
            "text": "date_from: дата ГГГГ-ММ-ДД",
            "why": "дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля)",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_to: дата ГГГГ-ММ-ДД",
            "why": "то же для date_to",
            "todo": "передайте дату вида 2026-11-20"
          },
          {
            "status": 400,
            "text": "date_from: дата от 2000-01-01 до 2100-12-31",
            "why": "date_from раньше 2000-01-01 или позже 2100-12-31",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to: дата от 2000-01-01 до 2100-12-31",
            "why": "то же для date_to",
            "todo": "передайте дату в этих пределах"
          },
          {
            "status": 400,
            "text": "date_to раньше date_from",
            "why": "конец периода раньше начала",
            "todo": "поменяйте даты местами"
          },
          {
            "status": 400,
            "text": "период больше 93 суток",
            "why": "между date_from и date_to больше 93 суток включительно",
            "todo": "разбейте период на части"
          },
          {
            "status": 400,
            "text": "limit: целое 1–100",
            "why": "limit не целое или вне 1–100",
            "todo": "передайте limit от 1 до 100"
          },
          {
            "status": 400,
            "text": "cursor: неверный курсор",
            "why": "cursor не из next_cursor прошлой страницы",
            "todo": "передайте next_cursor прошлого ответа как есть"
          }
        ],
        "x-limit": "stats"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Auth-Token",
        "description": "ключ API аккаунта bk_…"
      },
      "PanelSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "bk_s",
        "description": "вход в панель (cookie сессии браузера). По ключу API такие методы отвечают 403"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string",
            "description": "текст ошибки дословно: по нему ветвится вызывающий код",
            "example": "проект не найден"
          }
        },
        "required": [
          "ok",
          "error"
        ],
        "additionalProperties": false
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 7
          },
          "login": {
            "type": "string",
            "example": "client1"
          },
          "role": {
            "type": "string",
            "enum": [
              "client"
            ],
            "example": "client"
          },
          "parent_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "реселлер субаккаунта; null — обычный аккаунт",
            "example": null
          },
          "reseller": {
            "type": "boolean",
            "description": "может заводить субаккаунты",
            "example": false
          },
          "verified": {
            "type": "boolean",
            "description": "проверенный клиент: при нуле проекты идут ещё credit_days суток",
            "example": false
          },
          "price_kop": {
            "type": "integer",
            "description": "цена клика и разового задания, копейки",
            "example": 10
          },
          "balance_kop": {
            "type": "integer",
            "description": "баланс, копейки",
            "example": 150000
          },
          "negative_since": {
            "type": [
              "string",
              "null"
            ],
            "description": "с какого момента баланс ≤ 0",
            "format": "date-time",
            "example": null
          },
          "credit_days": {
            "type": "integer",
            "description": "суток кредита проверенного клиента",
            "example": 5
          },
          "stop": {
            "type": [
              "string",
              "null"
            ],
            "description": "стоп аккаунта: blocked — заблокирован, balance — нет денег; null — работает",
            "enum": [
              "blocked",
              "balance",
              null
            ],
            "example": null
          }
        },
        "required": [
          "id",
          "login",
          "role",
          "parent_id",
          "reseller",
          "verified",
          "price_kop",
          "balance_kop",
          "negative_since",
          "credit_days",
          "stop"
        ],
        "additionalProperties": false
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 3
          },
          "prefix": {
            "type": "string",
            "description": "первые 10 символов ключа для узнавания",
            "example": "bk_Xq3v9Lm"
          },
          "name": {
            "type": "string",
            "example": "сервер интеграции"
          },
          "created_at": {
            "type": "string",
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T07:15:00+00:00"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "не чаще раза в минуту",
            "format": "date-time",
            "example": "2026-11-20T09:02:11+00:00"
          },
          "last_ip": {
            "type": [
              "string",
              "null"
            ],
            "example": "203.0.113.5"
          }
        },
        "required": [
          "id",
          "prefix",
          "name",
          "created_at",
          "last_used_at",
          "last_ip"
        ],
        "additionalProperties": false
      },
      "ApiKeyCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 3
          },
          "key": {
            "type": "string",
            "description": "ключ целиком: показывается один раз, в панели хранится только sha256",
            "example": "bk_Xq3v9LmT2pR8sW4nY6bK1cD5fG7hJ0aZ9eQ3uI8oP2x"
          },
          "prefix": {
            "type": "string",
            "example": "bk_Xq3v9Lm"
          },
          "name": {
            "type": "string",
            "example": "сервер интеграции"
          },
          "created_at": {
            "type": "string",
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T07:15:00+00:00"
          }
        },
        "required": [
          "id",
          "key",
          "prefix",
          "name",
          "created_at"
        ],
        "additionalProperties": false
      },
      "Performance": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "сутки МСК",
            "format": "date",
            "example": "2026-11-20"
          },
          "plan_clicks": {
            "type": "integer",
            "description": "сумма лимитов в сутки включённых проектов без стопа",
            "example": 1200
          },
          "clicked": {
            "type": "integer",
            "description": "кликов за сутки МСК (stat_day, отставание около 10 мин)",
            "example": 418
          },
          "not_found": {
            "type": "integer",
            "description": "«сайт не найден» за сутки",
            "example": 37
          },
          "other": {
            "type": "integer",
            "description": "прочие исходы за сутки: гео, капча, сбой",
            "example": 12
          },
          "spent_kop": {
            "type": "integer",
            "description": "списано за сутки МСК",
            "example": 4180
          },
          "oneoff": {
            "type": "object",
            "properties": {
              "new": {
                "type": "integer",
                "example": 3
              },
              "running": {
                "type": "integer",
                "example": 12
              },
              "done": {
                "type": "integer",
                "description": "за сутки МСК"
              },
              "expired": {
                "type": "integer",
                "description": "за сутки МСК"
              }
            },
            "required": [
              "new",
              "running",
              "done",
              "expired"
            ],
            "additionalProperties": false
          },
          "balance_kop": {
            "type": "integer",
            "example": 150000
          },
          "days_left": {
            "type": [
              "number",
              "null"
            ],
            "description": "баланс / средний расход в сутки за 7 суток; null — расхода не было",
            "example": 35.7
          }
        },
        "required": [
          "date",
          "plan_clicks",
          "clicked",
          "not_found",
          "other",
          "spent_kop",
          "oneoff",
          "balance_kop",
          "days_left"
        ],
        "additionalProperties": false
      },
      "Balance": {
        "type": "object",
        "properties": {
          "balance_kop": {
            "type": "integer",
            "example": 150000
          },
          "price_kop": {
            "type": "integer",
            "example": 10
          },
          "verified": {
            "type": "boolean",
            "example": false
          },
          "credit_days": {
            "type": "integer",
            "example": 5
          },
          "credit_limit_kop": {
            "type": [
              "integer",
              "null"
            ],
            "description": "кредитный лимит; null — по умолчанию панели",
            "example": null
          },
          "negative_since": {
            "type": [
              "string",
              "null"
            ],
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": null
          },
          "stop": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "blocked",
              "balance",
              null
            ],
            "example": null
          },
          "spent_today_kop": {
            "type": "integer",
            "description": "списано за сутки МСК",
            "example": 3400
          },
          "spent_7d_kop": {
            "type": "integer",
            "description": "списано за 7 суток",
            "example": 21000
          }
        },
        "required": [
          "balance_kop",
          "price_kop",
          "verified",
          "credit_days",
          "credit_limit_kop",
          "negative_since",
          "stop",
          "spent_today_kop",
          "spent_7d_kop"
        ],
        "additionalProperties": false
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 88123
          },
          "kind": {
            "type": "string",
            "description": "deposit — пополнение, charge — списание за клики или разовое задание, refund — возврат, adjust — корректировка, transfer — перевод реселлер ↔ субаккаунт, commission — комиссия реселлера: из оплаченной части списания субаккаунта, списание в долг Комиссии не даёт (строка с 0)",
            "enum": [
              "deposit",
              "charge",
              "refund",
              "adjust",
              "transfer",
              "commission"
            ],
            "example": "charge"
          },
          "amount_kop": {
            "type": "integer",
            "description": "> 0 — зачисление, < 0 — списание",
            "example": -40
          },
          "balance_after": {
            "type": "integer",
            "description": "баланс после строки",
            "example": 149960
          },
          "clicks": {
            "type": [
              "integer",
              "null"
            ],
            "description": "charge и commission: кликов",
            "example": 4
          },
          "comment": {
            "type": [
              "string",
              "null"
            ],
            "description": "у transfer субаккаунта — «пополнение от реселлера» или «возврат реселлеру»: логин и заметку реселлера субаккаунт не видит",
            "example": "клики 07:10–07:15"
          },
          "created_at": {
            "type": "string",
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T07:15:00+00:00"
          },
          "project_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 31
          },
          "domain": {
            "type": [
              "string",
              "null"
            ],
            "description": "домен проекта",
            "example": "example.com"
          },
          "oneoff_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "разовое задание",
            "example": null
          },
          "peer_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "transfer, commission: другой аккаунт; субаккаунту — null",
            "example": null
          }
        },
        "required": [
          "id",
          "kind",
          "amount_kop",
          "balance_after",
          "clicks",
          "comment",
          "created_at",
          "project_id",
          "domain",
          "oneoff_id",
          "peer_id"
        ],
        "additionalProperties": false
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1042
          },
          "domain": {
            "type": "string",
            "example": "example.com"
          },
          "note": {
            "type": "string",
            "description": "заметка (название) проекта",
            "example": "Диваны"
          },
          "enabled": {
            "type": "boolean",
            "description": "желание клиента",
            "example": true
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "стоп от панели; во флоте проект идёт, только если enabled и stop_reason null",
            "enum": [
              "blocked",
              "budget",
              "balance",
              null
            ],
            "example": null
          },
          "pending": {
            "type": "boolean",
            "description": "вкл/выкл ещё не записан во флот: воркер пишет за секунды",
            "example": false
          },
          "limit_day": {
            "type": "integer",
            "description": "сумма лимитов включённых ключей в сутки, N@дни — как N/дни. Сразу после `POST /projects` (до сверки, до 10 мин) — вместе с выключенными",
            "example": 1200
          },
          "keys": {
            "type": "integer",
            "description": "включённых ключей (Заданий) во флоте. Сразу после `POST /projects` (до сверки, до 10 мин) — вместе с выключенными",
            "example": 25
          },
          "budget_kop": {
            "type": [
              "integer",
              "null"
            ],
            "description": "бюджет на весь срок; null — без бюджета",
            "example": null
          },
          "spent_kop": {
            "type": "integer",
            "description": "списано за всё время",
            "example": 4180
          },
          "today": {
            "type": "object",
            "properties": {
              "clicked": {
                "type": "integer",
                "example": 418
              },
              "not_found": {
                "type": "integer",
                "example": 37
              },
              "other": {
                "type": "integer",
                "description": "geo_fail + captcha + error",
                "example": 12
              }
            },
            "required": [
              "clicked",
              "not_found",
              "other"
            ],
            "additionalProperties": false
          },
          "total_clicked": {
            "type": "integer",
            "description": "кликов за всё время в статистике",
            "example": 15230
          },
          "avg_position": {
            "type": [
              "number",
              "null"
            ],
            "description": "средняя Позиция без бренда",
            "example": 4.2
          },
          "editable": {
            "type": "boolean",
            "description": "true — ключи правятся методами `/projects/{id}/keys`: у проекта один Список целиком и в нём не больше одного сайта. false — ключи через API не правятся",
            "example": true
          }
        },
        "required": [
          "id",
          "domain",
          "note",
          "enabled",
          "stop_reason",
          "pending",
          "limit_day",
          "keys",
          "budget_kop",
          "spent_kop",
          "today",
          "total_clicked",
          "avg_position",
          "editable"
        ],
        "additionalProperties": false
      },
      "KeyIn": {
        "type": "object",
        "properties": {
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "страница сайта (example.com/catalog, со схемой или без), без ; | # и пробелов, до 500 символов: клик сначала по ней; null — домен проекта",
            "example": "example.com/catalog"
          },
          "key": {
            "type": "string",
            "description": "поисковый запрос, 1–200 символов без ; и |",
            "minLength": 1,
            "maxLength": 200,
            "example": "купить диван москва"
          },
          "brands": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "description": "бренд-слова: «ключ слово» ищется, если по ключу сайт не нашёлся",
            "maxItems": 20,
            "example": [
              "ikea"
            ]
          },
          "clicks": {
            "type": "integer",
            "description": "кликов в сутки МСК",
            "minimum": 1,
            "maximum": 100000,
            "example": 4
          },
          "every_days": {
            "type": "integer",
            "description": "раз в сколько суток Задание выдаётся (Шанс 1/every_days)",
            "minimum": 1,
            "maximum": 365,
            "default": 1,
            "example": 1
          },
          "region": {
            "description": "регион Яндекса lr (213) или спинтакс {213|2}: число или строка; null — любой регион",
            "oneOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 99999999
              },
              {
                "type": "string",
                "pattern": "^(\\d{1,8}|\\{[0-9{}|]+\\})$"
              },
              {
                "type": "null"
              }
            ],
            "example": 213
          },
          "host_brand": {
            "type": [
              "string",
              "null"
            ],
            "description": "Хост-бренд вручную, 1–100 символов; null — из домена",
            "maxLength": 100,
            "example": null
          }
        },
        "required": [
          "key",
          "clicks"
        ],
        "additionalProperties": false,
        "description": "Ключ проекта в запросе. Поля вывода `GET /projects/{id}/keys` (`id`, `enabled`, `today`) не принимаются: 400 `items[<i>].<поле>: неизвестное поле`."
      },
      "Key": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "task_key: 16 hex. Меняется вместе с url, ключом без учёта регистра или регионом",
            "example": "3f2a9c0d1e4b5a67"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "страница сайта; null — домен проекта",
            "example": "example.com/catalog"
          },
          "key": {
            "type": "string",
            "example": "купить диван москва"
          },
          "brands": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "ikea"
            ]
          },
          "clicks": {
            "type": "integer",
            "example": 4
          },
          "every_days": {
            "type": "integer",
            "example": 1
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "description": "регион lr или спинтакс строкой; null — любой регион",
            "example": "213"
          },
          "host_brand": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "today": {
            "type": "object",
            "properties": {
              "clicked": {
                "type": "integer",
                "example": 418
              },
              "not_found": {
                "type": "integer",
                "example": 37
              },
              "other": {
                "type": "integer",
                "description": "geo_fail + captcha + error",
                "example": 12
              }
            },
            "required": [
              "clicked",
              "not_found",
              "other"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "url",
          "key",
          "brands",
          "clicks",
          "every_days",
          "region",
          "host_brand",
          "enabled",
          "today"
        ],
        "additionalProperties": false
      },
      "ImportResult": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "example": "example.com",
            "description": "домен"
          },
          "project_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 31
          },
          "existing": {
            "type": "boolean",
            "description": "проект уже был: ключи заменены (`POST /projects`)",
            "example": false
          },
          "tasks": {
            "type": [
              "integer",
              "null"
            ],
            "description": "ключей во флоте после записи",
            "example": 25
          },
          "limit": {
            "type": [
              "number",
              "null"
            ],
            "description": "сумма лимитов после записи",
            "example": 1200.0
          },
          "inserted": {
            "type": [
              "integer",
              "null"
            ],
            "example": 25
          },
          "updated": {
            "type": [
              "integer",
              "null"
            ],
            "example": 0
          },
          "deleted": {
            "type": [
              "integer",
              "null"
            ],
            "example": 0
          },
          "dups": {
            "type": "integer",
            "description": "повторы строк: пропущены",
            "example": 0
          },
          "errors": {
            "type": "integer",
            "description": "строк не принято",
            "example": 0
          },
          "error_rows": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "n": {
                  "type": "integer",
                  "description": "номер строки"
                },
                "text": {
                  "type": "string",
                  "description": "текст разбора Пульта дословно"
                }
              },
              "required": [
                "n",
                "text"
              ],
              "additionalProperties": false
            },
            "description": "первые 5 непринятых строк"
          },
          "error": {
            "type": "string",
            "description": "только у домена, который не записан: тогда, кроме domain, других полей нет"
          }
        },
        "required": [
          "domain"
        ],
        "additionalProperties": false,
        "description": "Итог записи одного домена: либо поля итога import, либо domain и error."
      },
      "DayStat": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "example": "2026-11-19"
          },
          "sessions": {
            "type": "integer",
            "description": "Целевых Сессий",
            "example": 470
          },
          "clicked": {
            "type": "integer",
            "example": 418
          },
          "not_found": {
            "type": "integer",
            "example": 37
          },
          "other": {
            "type": "integer",
            "example": 12
          },
          "clicked_plain": {
            "type": "integer",
            "description": "клик без бренда",
            "example": 390
          },
          "clicked_brand": {
            "type": "integer",
            "description": "клик после Поиска с брендом",
            "example": 28
          },
          "plain_tried": {
            "type": "integer",
            "description": "Поисков без бренда",
            "example": 460
          },
          "plain_top10": {
            "type": "integer",
            "description": "из них сайт в первой десятке",
            "example": 401
          },
          "avg_position": {
            "type": [
              "number",
              "null"
            ],
            "description": "средняя Позиция без бренда",
            "example": 4.2
          },
          "spent_kop": {
            "type": "integer",
            "description": "списано за сутки",
            "example": 4180
          }
        },
        "required": [
          "date",
          "sessions",
          "clicked",
          "not_found",
          "other",
          "clicked_plain",
          "clicked_brand",
          "plain_tried",
          "plain_top10",
          "avg_position",
          "spent_kop"
        ],
        "additionalProperties": false
      },
      "KeyStat": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "task_key",
            "example": "3f2a9c0d1e4b5a67"
          },
          "key": {
            "type": "string",
            "example": "купить диван москва"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "страница ключа из Сессий флота; null — страница не задана (домен проекта), Сессий за 40 суток нет или флот не ответил за 15 с",
            "example": "example.com/catalog"
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "description": "регион ключа (lr) из Сессий флота; null — регион не задан, Сессий за 40 суток нет или флот не ответил за 15 с",
            "example": "213"
          },
          "sessions": {
            "type": "integer",
            "example": 470
          },
          "clicked": {
            "type": "integer",
            "example": 418
          },
          "not_found": {
            "type": "integer",
            "example": 37
          },
          "other": {
            "type": "integer",
            "example": 12
          },
          "not_found_pct": {
            "type": "number",
            "description": "доля not_found от clicked + not_found + other, %, один знак после запятой; исходов нет — 0",
            "example": 7.9
          },
          "avg_position": {
            "type": [
              "number",
              "null"
            ],
            "example": 4.2
          },
          "best_position": {
            "type": [
              "integer",
              "null"
            ],
            "example": 1
          },
          "hint_code": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "other_host",
              "seen",
              "never",
              null
            ],
            "description": "почему ключ мог не найтись (таблица в описании метода); null — not_found 0",
            "example": "seen"
          },
          "hint": {
            "type": [
              "string",
              "null"
            ],
            "description": "текст подсказки для человека; null — not_found 0",
            "example": "Сегодня сайт был в выдаче (лучшая позиция #1), в этих попытках не попал на просмотренные страницы"
          }
        },
        "required": [
          "id",
          "key",
          "url",
          "region",
          "sessions",
          "clicked",
          "not_found",
          "other",
          "not_found_pct",
          "avg_position",
          "best_position",
          "hint_code",
          "hint"
        ],
        "additionalProperties": false
      },
      "TaskIn": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "свой id задания, 1–64 символа. Уникален на аккаунт среди заданий api и panel: повтор id возвращает прежнее задание с duplicate true",
            "minLength": 1,
            "maxLength": 64,
            "example": "a1"
          },
          "site": {
            "type": "string",
            "description": "домен или URL сайта: example.com или https://example.com/catalog; query и # отбрасываются, сравнение с выдачей идёт по хосту в нижнем регистре и пути",
            "minLength": 3,
            "maxLength": 300,
            "example": "example.com"
          },
          "key": {
            "type": "string",
            "description": "поисковый запрос, 1–200 символов без ; и |",
            "minLength": 1,
            "maxLength": 200,
            "example": "купить диван москва"
          },
          "region": {
            "description": "регион Яндекса lr, целое 1–10000000 или строка из цифр",
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1,
                "maximum": 10000000
              },
              {
                "type": "string",
                "pattern": "^[0-9]{1,8}$"
              }
            ],
            "example": 213
          },
          "brand": {
            "type": [
              "string",
              "null"
            ],
            "description": "бренд-слово или фраза до 100 символов без ; и |",
            "maxLength": 100,
            "example": "IKEA"
          },
          "brand_mode": {
            "type": "string",
            "description": "none — Поиск только по ключу; if_not_found — по ключу, не нашёлся — «ключ бренд»; always — сразу «ключ бренд». Умолчание: if_not_found при brand, иначе none. if_not_found без brand исполняется как none; always без brand — 400",
            "enum": [
              "none",
              "if_not_found",
              "always"
            ],
            "example": "if_not_found"
          },
          "serp_pages": {
            "type": "integer",
            "description": "страниц выдачи в Поиске",
            "minimum": 1,
            "maximum": 5,
            "default": 3,
            "example": 2
          }
        },
        "required": [
          "site",
          "key",
          "region"
        ],
        "additionalProperties": false
      },
      "TaskResult": {
        "type": "object",
        "properties": {
          "outcome": {
            "type": "string",
            "description": "clicked — кликнули; not_found — сайта нет на serp_pages страницах",
            "enum": [
              "clicked",
              "not_found"
            ],
            "example": "clicked"
          },
          "position": {
            "type": "integer",
            "description": "сквозная Позиция клика по просмотренным страницам органики, с 1; 0 — не найден",
            "example": 3
          },
          "page": {
            "type": "integer",
            "description": "страница выдачи клика; 0 — не найден",
            "example": 1
          },
          "found_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "URL, по которому кликнули; null — not_found или флот не записал URL клика (тогда смотрите landed_url)",
            "example": "https://example.com/catalog/divany"
          },
          "landed_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "адрес вкладки после клика",
            "example": "https://example.com/catalog/divany"
          },
          "found_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "url — совпала страница, domain — домен",
            "enum": [
              "url",
              "domain",
              null
            ],
            "example": "url"
          },
          "brand_used": {
            "type": "boolean",
            "description": "клик после Поиска «ключ бренд»",
            "example": false
          },
          "plain_position": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Позиция в Поиске без бренда; null — не нашёлся или Поиска не было",
            "example": 3
          }
        },
        "required": [
          "outcome",
          "position",
          "page",
          "found_url",
          "landed_url",
          "found_by",
          "brand_used",
          "plain_position"
        ],
        "additionalProperties": false
      },
      "Task": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1042
          },
          "client_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "свой id задания (items[].id, до 64 символов) или task_id Источника (до 500 символов); null — без id",
            "example": "a1"
          },
          "origin": {
            "type": "string",
            "description": "api — POST /tasks, panel — экран «Разовые», source — Источник по API.md",
            "enum": [
              "api",
              "panel",
              "source"
            ],
            "example": "api"
          },
          "status": {
            "type": "string",
            "description": "new — принято, ждёт записи во флот; running — во флоте; done — итог clicked или not_found; expired — нет итога за срок; rejected — не принято флотом или (задание Источника) проверкой; canceled — снято",
            "enum": [
              "new",
              "running",
              "done",
              "expired",
              "rejected",
              "canceled"
            ],
            "example": "done"
          },
          "success": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "true — done; false — expired, rejected, canceled; null — ещё в работе",
            "example": true
          },
          "site": {
            "type": "string",
            "example": "example.com",
            "description": "хост в нижнем регистре и путь без схемы, query, # и / по краям: так флот сравнивает сайт с выдачей. Сопоставляйте задания по client_id, не по site"
          },
          "key": {
            "type": "string",
            "example": "купить диван москва"
          },
          "region": {
            "type": "integer",
            "example": 213
          },
          "brand": {
            "type": [
              "string",
              "null"
            ],
            "example": "IKEA"
          },
          "brand_mode": {
            "type": "string",
            "enum": [
              "none",
              "if_not_found",
              "always"
            ],
            "example": "if_not_found"
          },
          "serp_pages": {
            "type": "integer",
            "example": 2
          },
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TaskResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "attempts": {
            "type": "integer",
            "description": "Целевых Сессий с исходом error, captcha, geo_fail: не списываются, задание идёт снова",
            "example": 0
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ],
            "description": "«<outcome>: <reason>» последней такой Сессии",
            "example": null
          },
          "reject_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "rejected: текст дословно",
            "example": null
          },
          "charged_kop": {
            "type": "integer",
            "description": "списано за задание (цена клика на момент итога); 0 — не списывалось",
            "example": 10
          },
          "created_at": {
            "type": "string",
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T07:15:00+00:00"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "записано во флот",
            "format": "date-time",
            "example": "2026-11-20T07:15:30+00:00"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T07:21:04+00:00"
          },
          "expires_at": {
            "type": "string",
            "description": "срок задания: new к нему — expired сразу; running — через запас срока 5 мин",
            "format": "date-time",
            "example": "2026-11-20T08:15:00+00:00"
          }
        },
        "required": [
          "id",
          "client_id",
          "origin",
          "status",
          "success",
          "site",
          "key",
          "region",
          "brand",
          "brand_mode",
          "serp_pages",
          "result",
          "attempts",
          "last_error",
          "reject_reason",
          "charged_kop",
          "created_at",
          "started_at",
          "finished_at",
          "expires_at"
        ],
        "additionalProperties": false
      },
      "Queue": {
        "type": "object",
        "properties": {
          "new": {
            "type": "integer",
            "example": 3
          },
          "running": {
            "type": "integer",
            "example": 12
          },
          "today": {
            "type": "object",
            "properties": {
              "done": {
                "type": "integer"
              },
              "expired": {
                "type": "integer"
              },
              "rejected": {
                "type": "integer"
              },
              "canceled": {
                "type": "integer"
              }
            },
            "required": [
              "done",
              "expired",
              "rejected",
              "canceled"
            ],
            "description": "за сутки МСК",
            "additionalProperties": false
          },
          "fleet_max": {
            "type": "integer",
            "description": "разовых заданий во флоте одновременно на всю панель",
            "example": 2000
          }
        },
        "required": [
          "new",
          "running",
          "today",
          "fleet_max"
        ],
        "additionalProperties": false
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "url": {
            "type": [
              "string",
              "null"
            ],
            "example": "https://example.com/bk-hook"
          },
          "secret_set": {
            "type": "boolean",
            "example": true
          },
          "secret_hint": {
            "type": [
              "string",
              "null"
            ],
            "description": "первые 4 символа секрета",
            "example": "9f3a"
          },
          "last_delivery": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "at": {
                "type": "string",
                "description": "время ISO 8601 UTC",
                "format": "date-time"
              },
              "http_status": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "at",
              "http_status",
              "error"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "url",
          "secret_set",
          "secret_hint",
          "last_delivery"
        ],
        "additionalProperties": false
      },
      "WebhookEvent": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "task.finished",
              "ping"
            ],
            "example": "task.finished"
          },
          "task": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Task"
              },
              {
                "type": "null"
              }
            ]
          },
          "sent_at": {
            "type": "string",
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T07:21:05+00:00"
          }
        },
        "required": [
          "event",
          "task",
          "sent_at"
        ],
        "description": "Тело вебхука. Заголовки: X-BK-Event, X-BK-Delivery, X-BK-Timestamp, X-BK-Signature = sha256=<hex HMAC-SHA256(секрет, «<X-BK-Timestamp>.» + сырое тело)>",
        "additionalProperties": false
      },
      "Source": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 5
          },
          "account_id": {
            "type": "integer",
            "example": 7
          },
          "login": {
            "type": "string",
            "example": "client1"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "для старых клиентов: основа, если адреса ровно `<url>/task` и `<url>/result` (основа без `?`, `#` и `/` в конце); иначе null. Запросы идут на `task_url` и `result_url`",
            "example": "https://tasks.example.com/api"
          },
          "task_url": {
            "type": "string",
            "description": "полный адрес забора: GET ровно на него",
            "example": "https://tasks.example.com/api/task"
          },
          "result_url": {
            "type": "string",
            "description": "полный адрес результатов: POST ровно на него",
            "example": "https://tasks.example.com/api/result"
          },
          "auth_header": {
            "type": [
              "string",
              "null"
            ],
            "description": "имя заголовка авторизации",
            "example": "X-Api-Key"
          },
          "auth_value_set": {
            "type": "boolean",
            "description": "значение задано; не отдаётся",
            "example": true
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "state": {
            "type": "string",
            "description": "off — выключен; ok — задания идут; idle — у сервера нет заданий (204), запрос раз в 15 с; error — ошибка, повтор с паузой 15…600 с; auth — сервер отказал (401, 403), забор выключен; paused — пауза без запросов (деньги, потолок суток, разовые выключены)",
            "enum": [
              "off",
              "ok",
              "idle",
              "error",
              "auth",
              "paused"
            ],
            "example": "ok"
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ],
            "description": "последняя ошибка забора дословно (таблица в описании GET /source); не стирается при успехе — сравнивайте last_error_at с last_ok_at",
            "example": null
          },
          "last_error_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": null
          },
          "last_ok_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T09:01:58+00:00"
          },
          "inflight": {
            "type": "integer",
            "description": "заданий Источника в работе",
            "example": 140
          },
          "inflight_max": {
            "type": "integer",
            "description": "потолок «в работе»; NULL у Источника — умолчание панели",
            "example": 200
          },
          "today": {
            "type": "integer",
            "description": "взято за сутки МСК",
            "example": 3180
          },
          "day_max": {
            "type": "integer",
            "description": "суточный потолок панели; NULL у Источника — умолчание панели",
            "example": 100000
          },
          "day_limit": {
            "type": [
              "integer",
              "null"
            ],
            "description": "свой суточный потолок клиента",
            "example": 5000
          },
          "results_pending": {
            "type": "integer",
            "description": "результатов ждут отправки",
            "example": 0
          },
          "results_failed": {
            "type": "integer",
            "description": "результатов не доставлено",
            "example": 0
          }
        },
        "required": [
          "id",
          "account_id",
          "login",
          "url",
          "task_url",
          "result_url",
          "auth_header",
          "auth_value_set",
          "enabled",
          "state",
          "last_error",
          "last_error_at",
          "last_ok_at",
          "inflight",
          "inflight_max",
          "today",
          "day_max",
          "day_limit",
          "results_pending",
          "results_failed"
        ],
        "additionalProperties": false
      },
      "SourceIn": {
        "type": "object",
        "properties": {
          "task_url": {
            "type": "string",
            "description": "полный адрес забора: запрос GET идёт ровно на него. http или https, без логина, пароля и `#`, параметры после `?` разрешены, до 500 символов, адрес из публичного интернета. Обязателен, если нет `url`",
            "maxLength": 500,
            "example": "https://tasks.example.com/api/task"
          },
          "result_url": {
            "type": "string",
            "description": "полный адрес результатов: запрос POST идёт ровно на него. http или https, без логина, пароля и `#`, параметры после `?` разрешены, до 500 символов, адрес из публичного интернета. Обязателен, если нет `url`",
            "maxLength": 500,
            "example": "https://tasks.example.com/api/result"
          },
          "url": {
            "type": "string",
            "description": "прежнее поле вместо двух адресов: база https://host[:port][/путь], панель запишет `<url>/task` и `<url>/result`. Без `?`, `#`, логина и пароля; без `/` в конце — до 493 символов, `/` в конце снимается. Вместе с `task_url` или `result_url` — 400",
            "maxLength": 500,
            "example": "https://tasks.example.com/api"
          },
          "auth_header": {
            "type": [
              "string",
              "null"
            ],
            "description": "имя заголовка: латиница, цифры, -; не передано — прежнее, null — без авторизации",
            "pattern": "^[A-Za-z0-9-]{1,64}$",
            "example": "X-Api-Key"
          },
          "auth_value": {
            "type": [
              "string",
              "null"
            ],
            "description": "значение заголовка: до 1000 печатных символов ASCII; не передано — прежнее",
            "maxLength": 1000
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "day_limit": {
            "type": [
              "integer",
              "null"
            ],
            "description": "свой суточный потолок; null — потолок панели; не передано — прежнее",
            "minimum": 0,
            "example": 5000
          }
        },
        "required": [
          "enabled"
        ],
        "additionalProperties": false
      },
      "Subaccount": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 58
          },
          "login": {
            "type": "string",
            "example": "client1"
          },
          "telegram": {
            "type": "string",
            "description": "логин Telegram без @",
            "example": "client1_tg"
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "example": "Иванов, мебель"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "blocked"
            ],
            "example": "active"
          },
          "price_kop": {
            "type": "integer",
            "description": "цена клика субаккаунта",
            "example": 10
          },
          "balance_kop": {
            "type": "integer",
            "example": 150000
          },
          "negative_since": {
            "type": [
              "string",
              "null"
            ],
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": null
          },
          "projects": {
            "type": "integer",
            "description": "проектов, в том числе скрытых",
            "example": 3
          },
          "created_at": {
            "type": "string",
            "description": "время ISO 8601 UTC",
            "format": "date-time",
            "example": "2026-11-20T07:15:00+00:00"
          },
          "spent_today_kop": {
            "type": "integer",
            "description": "списано за сутки МСК",
            "example": 3400
          },
          "clicked_today": {
            "type": "integer",
            "description": "списанных кликов за сутки МСК",
            "example": 340
          },
          "parent_id": {
            "type": "integer",
            "description": "реселлер субаккаунта",
            "example": 7
          },
          "admin_blocked": {
            "type": "boolean",
            "description": "Блок поставил админ: снять его может только админ",
            "example": false
          }
        },
        "required": [
          "id",
          "login",
          "telegram",
          "label",
          "status",
          "price_kop",
          "balance_kop",
          "negative_since",
          "projects",
          "created_at",
          "spent_today_kop",
          "clicked_today",
          "parent_id",
          "admin_blocked"
        ],
        "additionalProperties": false
      },
      "SubaccountIn": {
        "type": "object",
        "properties": {
          "login": {
            "type": "string",
            "description": "3–32 символа: латиница, цифры, _ . -",
            "pattern": "^[A-Za-z0-9_.-]{3,32}$",
            "example": "client1"
          },
          "password": {
            "type": "string",
            "description": "от 8 символов; не передан — сгенерируется и вернётся в ответе",
            "minLength": 8,
            "maxLength": 128
          },
          "telegram": {
            "type": "string",
            "description": "@name; не передан — пусто (Telegram реселлера не копируется)",
            "example": "client1_tg"
          },
          "price_kop": {
            "type": "integer",
            "description": "цена клика; не ниже цены реселлера; умолчание — цена реселлера",
            "minimum": 0,
            "maximum": 100000,
            "example": 10
          },
          "label": {
            "type": "string",
            "maxLength": 100,
            "example": "Иванов, мебель"
          }
        },
        "required": [
          "login"
        ]
      },
      "SummaryRow": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "integer",
            "example": 58
          },
          "login": {
            "type": "string",
            "example": "client1"
          },
          "parent_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 7
          },
          "opening_kop": {
            "type": "integer",
            "description": "баланс на начало периода: balance_after последней строки до него; 0 — строк не было",
            "example": 100000
          },
          "deposits_kop": {
            "type": "integer",
            "example": 0
          },
          "adjust_kop": {
            "type": "integer",
            "example": 0
          },
          "transfer_in_kop": {
            "type": "integer",
            "example": 50000
          },
          "transfer_out_kop": {
            "type": "integer",
            "description": "по модулю",
            "example": 0
          },
          "commission_kop": {
            "type": "integer",
            "example": 0
          },
          "charged_kop": {
            "type": "integer",
            "description": "списано, по модулю",
            "example": 21000
          },
          "clicks": {
            "type": "integer",
            "description": "списанных кликов",
            "example": 2100
          },
          "oneoff_clicked": {
            "type": "integer",
            "example": 120
          },
          "oneoff_not_found": {
            "type": "integer",
            "example": 14
          },
          "closing_kop": {
            "type": "integer",
            "description": "баланс на конец периода",
            "example": 129000
          }
        },
        "required": [
          "account_id",
          "login",
          "parent_id",
          "opening_kop",
          "deposits_kop",
          "adjust_kop",
          "transfer_in_kop",
          "transfer_out_kop",
          "commission_kop",
          "charged_kop",
          "clicks",
          "oneoff_clicked",
          "oneoff_not_found",
          "closing_kop"
        ],
        "additionalProperties": false
      }
    },
    "responses": {
      "BadRequest": {
        "description": "«тело — не JSON», «тело — не объект JSON», «параметр <имя>: <текст FastAPI>» (параметр не того типа или вне пределов)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "«нужен вход» или «ключ API не найден или отозван»",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "«аккаунт заблокирован: напишите админу в Telegram», «метод доступен только из панели: войдите на сайт»",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooMany": {
        "description": "«слишком много запросов: лимит N в минуту (bucket), повторите через S с»",
        "headers": {
          "Retry-After": {
            "description": "секунд до конца минуты",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "«внутренняя ошибка сервера: повторите позже» — необработанный сбой панели",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "parameters": {
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "next_cursor прошлой страницы",
        "schema": {
          "type": "string"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "строк на странице, 1–500, умолчание 100",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 500,
          "default": 100
        }
      },
      "Limit100": {
        "name": "limit",
        "in": "query",
        "description": "строк на странице, 1–100, умолчание 100",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 100
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "description": "ключ повтора запроса. Тот же ключ и то же тело — сохранённый ответ без повтора действия; другое тело — 409",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        }
      },
      "DateFrom": {
        "name": "date_from",
        "in": "query",
        "description": "первые сутки МСК, ГГГГ-ММ-ДД, от 2000-01-01 до 2100-12-31",
        "schema": {
          "type": "string",
          "format": "date"
        },
        "example": "2026-11-01"
      },
      "DateTo": {
        "name": "date_to",
        "in": "query",
        "description": "последние сутки МСК включительно, от 2000-01-01 до 2100-12-31",
        "schema": {
          "type": "string",
          "format": "date"
        },
        "example": "2026-11-20"
      },
      "ProjectId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9223372036854775807
        }
      },
      "Id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9223372036854775807
        }
      }
    }
  }
}
