# POST /search — веб-поиск

Все поля запроса и ответа собственного веб-поиска хаба, правила оплаты и ошибки.

`POST /web-search/api/v1/search` выполняет один поисковый запрос и возвращает ссылки с выдержками под заданную цель. Это собственный API хаба: вместо модельного `model` используется поле `provider`, а все его поля описаны ниже.

```bash
curl https://hub.coreinfra.ai/web-search/api/v1/search \
  -H "Authorization: Bearer $COREINFRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"okhta","objective":"Найдите документацию Rust","search_query":"Rust"}'
```

Фрагмент структуры ответа; идентификатор и выдержка сокращены:

```json
{
  "search_id": "...",
  "results": [
    {
      "url": "https://example.com/rust",
      "title": "Rust",
      "publish_date": null,
      "excerpts": ["..."]
    }
  ]
}
```

## Поля запроса и ответа

Это собственный интерфейс хаба; таблицы описывают весь запрос и ответ.

### Запрос

Все три поля обязательны, принимают строки и не имеют значений по умолчанию. Неизвестные поля отклоняются со статус-кодом `400`.

| Поле           | Значение                                                                                                                         |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `provider`     | Вариант поиска: `okhta` или `karpovka`; пустое или неизвестное имя отклоняется со статус-кодом `400`, недоступный сервис — `503` |
| `objective`    | Цель поиска, по которой подбираются выдержки; пустая строка или строка из пробельных символов отклоняется со статус-кодом `400`  |
| `search_query` | Одна поисковая строка; пустая строка или строка из пробельных символов отклоняется со статус-кодом `400`                         |

`karpovka` запрашивает до 10 результатов. Число результатов для `okhta` отдельным полем не задается.

### Ответ

Успешный вызов возвращает статус-код `200` и JSON. Список `results` может быть пустым.

| Поле                     | Тип               | Значение                                    |
| ------------------------ | ----------------- | ------------------------------------------- |
| `search_id`              | строка            | UUID запроса хаба                           |
| `results`                | массив объектов   | Результаты поиска                           |
| `results[].url`          | строка            | Адрес результата                            |
| `results[].title`        | строка или `null` | Заголовок                                   |
| `results[].publish_date` | строка или `null` | Дата публикации, если она есть в результате |
| `results[].excerpts`     | массив строк      | Выдержки под заданную цель                  |

Ответ не содержит модельного `usage` или суммы списания. До поиска резервируется стоимость запроса; после ответа учитываются запрос и число результатов по выбранному тарифу. Для `okhta` и `karpovka` включено 10 результатов, дополнительные результаты оплачиваются отдельно. Ошибка обращения к сервису освобождает резерв. Цены — на странице [«Тарифы»](https://hub.coreinfra.ai/pricing).

## Ошибки

| Статус-код | Условие                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400`      | Некорректный JSON, отсутствующее или неизвестное поле, пустой или неподдерживаемый `provider`, пустой `objective` или `search_query` |
| `502`      | Ошибка на стороне провайдера поиска при выполнении запроса                                                                           |
| `503`      | Выбранный сервис поиска временно недоступен                                                                                          |

Формат ошибок описан в [разделе веб-API](https://coreinfra.ru/docs/reference/web.md#errors); общие ошибки ключа, баланса, лимита расходов и размера запроса — в [общем справочнике](https://coreinfra.ru/docs/reference.md#errors).
