# API di ricerca

> Schede CVE, query sui bollettini, ricerca web, lettura di pagine e analisi di file, gli stessi dati che usa la chat.


Queste route danno alla CLI, all'estensione e al tuo codice i dati che usa la chat. Ogni organizzazione può fare 120 richieste al minuto. Non usano token, quindi non si pagano a token.

| Route | Cosa fa |
|---|---|
| `GET /v1/cve/{id}` | Una CVE con descrizione NVD, CVSS, CWE, EPSS, stato nel CISA KEV e riferimenti |
| `GET /v1/cve/search?q=&vendor=&cwe=&kev=true&min_cvss=&min_epss=&limit=` | Cerca nella copia locale |
| `GET /v1/kb/search?q=&domain=&source=&tool=&limit=` | Cerca nella knowledge base di sicurezza curata |
| `GET /v1/kb/{id}` | Legge un documento della knowledge base, paginato per sezione |
| `POST /v1/advisories/query` | Bollettini per un pacchetto e una versione |
| `POST /v1/web/search` | Risultati di ricerca web con titolo, URL ed estratto |
| `POST /v1/web/read` | Testo di una pagina pubblica, scaricata tramite un'uscita protetta |
| `POST /v1/files` | Carica un file per l'analisi statica |
| `GET /v1/files/{id}`, `GET /v1/files/{id}/content` | Stato e testo estratto |

```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"}'
```

## Knowledge base

`GET /v1/kb/search` restituisce passaggi da una knowledge base di sicurezza curata e con licenza, ognuno con fonte, licenza e attribuzione. Filtra per `domain` (web, api, mobile, offensive, tools, cloud, ir, attack), `source` o `tool`. Leggi il documento completo con `GET /v1/kb/{id}`, paginato con `from` e `limit`. È la stessa base che la chat legge da sola.

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

## File

`POST /v1/files` accetta i byte grezzi come corpo, fino a 32 MB, e il nome in `x-file-name`, codificato per URL quando ha caratteri non ASCII. Aggiungi `?wait=1` per aspettare l'analisi. Ogni file viene salvato cifrato con una scadenza di un'ora. La scadenza è registrata, ma l'eliminazione automatica non è ancora attiva, quindi il file resta finché non viene rimosso. Per farne rimuovere uno scrivi a legal@notholy.com. È un'archiviazione che chiedi tu, separata dall'inferenza, che non salva contenuti. I file vengono analizzati dentro una sandbox isolata senza rete, e nulla di quello che contengono viene eseguito.

```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` legge solo pagine pubbliche. Rifiuta gli indirizzi privati e non manda mai traffico verso target al posto tuo. Qualsiasi cosa dica una pagina viene trattata come dato, mai come istruzione.

Gli errori di queste route hanno la forma `{"error": {"code", "message"}}`; gli errori di chiave e di limite usano il formato OpenAI. Codici propri: `search_failed` e `read_failed` (502), `422` con il motivo quando `web/read` rifiuta una pagina, e `file_too_large` (413) sopra i 200 MB. Un caricamento tra 32 e 200 MB fallisce con `502 upstream_error`.

## Prossimi passi

- [CVE in chat](/it/chat/cves)
- [MCP](/it/mcp/local)