# Research API

> Записи CVE, запросы к бюллетеням, поиск в вебе, чтение страниц и анализ файлов — те же данные, что использует чат.


Эти маршруты дают CLI, расширению и вашему коду те же данные, что использует чат. Каждая организация может отправлять к ним 120 запросов в минуту. Токены они не расходуют, поэтому за токены не оплачиваются.

| Маршрут | Что делает |
|---|---|
| `GET /v1/cve/{id}` | Одна CVE с описанием из NVD, CVSS, CWE, EPSS, статусом в CISA KEV и ссылками |
| `GET /v1/cve/search?q=&vendor=&cwe=&kev=true&min_cvss=&min_epss=&limit=` | Поиск по зеркалу |
| `GET /v1/kb/search?q=&domain=&source=&tool=&limit=` | Поиск по отобранной базе знаний о безопасности |
| `GET /v1/kb/{id}` | Чтение одного документа базы знаний, постранично по разделам |
| `POST /v1/advisories/query` | Бюллетени для пакета и версии |
| `POST /v1/web/search` | Результаты поиска в вебе с заголовком, URL и сниппетом |
| `POST /v1/web/read` | Текст публичной страницы, загруженной через защищённый исходящий шлюз |
| `POST /v1/files` | Загрузка файла на статический анализ |
| `GET /v1/files/{id}`, `GET /v1/files/{id}/content` | Статус и извлечённый текст |

```bash test
curl https://api.notholy.com/v1/cve/CVE-2021-44228 -H "Authorization: Bearer $NOTHOLY_API_KEY"
```

```bash test
curl -X POST https://api.notholy.com/v1/advisories/query \
  -H "Authorization: Bearer $NOTHOLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ecosystem": "npm", "name": "lodash", "version": "4.17.15"}'
```

## База знаний

`GET /v1/kb/search` возвращает фрагменты из отобранной базы знаний о безопасности с разрешёнными лицензиями, у каждого указаны источник, лицензия и атрибуция. Фильтруйте по `domain` (web, api, mobile, offensive, tools, cloud, ir, attack), `source` или `tool`. Полный документ читается через `GET /v1/kb/{id}`, постранично с `from` и `limit`. Это та же база, которую чат читает сам.

```bash test
curl "https://api.notholy.com/v1/kb/search?q=ssrf+prevention&domain=web" -H "Authorization: Bearer $NOTHOLY_API_KEY"
```

## Файлы

`POST /v1/files` принимает сырые байты в теле запроса, до 32 МБ, а имя — в `x-file-name`, в URL-кодировке, если в нём есть символы не из ASCII. Добавьте `?wait=1`, чтобы дождаться анализа. Каждый файл хранится зашифрованным со сроком один час. Срок записывается, но автоудаление пока не работает, поэтому файл остаётся, пока его не удалят. Чтобы удалить файл, напишите на legal@notholy.com. Это хранение по вашему запросу, отдельно от инференса, который контент не хранит. Файлы разбираются в изолированной песочнице без сети, и ничего из них не исполняется.

```bash test
printf 'const q = "SELECT * FROM users WHERE id = " + req.query.id;\n' > handler.js
curl -X POST "https://api.notholy.com/v1/files?wait=1" \
  -H "Authorization: Bearer $NOTHOLY_API_KEY" \
  -H "x-file-name: handler.js" \
  --data-binary @handler.js
```

`web/read` только читает публичные страницы. Он отклоняет приватные адреса и никогда не шлёт трафик к целям за вас. Всё, что написано на странице, считается данными, а не инструкцией.

Ошибки этих маршрутов имеют вид `{"error": {"code", "message"}}`; ошибки ключа и лимитов приходят в формате OpenAI. Собственные коды: `search_failed` и `read_failed` (502), `422` с причиной, когда `web/read` отказывается читать страницу, и `file_too_large` (413) при размере больше 200 МБ. Загрузка от 32 до 200 МБ завершается ошибкой `502 upstream_error`.

## Что дальше

- [CVE в чате](/ru/chat/cves)
- [MCP](/ru/mcp/local)