> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API di web scraping

> L'API di web scraping Cleariflow offre l'estrazione di pagine renderizzate con JavaScript tramite un'interfaccia JSON RESTful moderna con protezione SSRF e opzioni di rendering flessibili.

## Per iniziare

<Card title="Scraping sincrono" icon="browser" href="scrape/scrape">
  L'endpoint `scrape` esegue una sessione del browser e restituisce HTML renderizzato in una singola richiesta — ideale per integrazioni a bassa latenza.
</Card>

<Card title="Job asincroni" icon="clock" href="scrape/jobs">
  Gli endpoint `jobs` accodano attività di scraping e permettono di verificare stato e risultati — ideali per alto volume o pagine lente.
</Card>

### Architettura REST

L'API di web scraping segue i principi REST, con URL prevedibili orientati alle risorse e codici di stato HTTP standard per un'integrazione fluida e la gestione degli errori.

### Sicurezza HTTPS

Tutte le comunicazioni API sono protette con TLS 1.2 o superiore per garantire integrità e privacy dei dati.

### Versioni dell'API

L'API di web scraping mantiene la compatibilità all'indietro tramite versionamento ed è attualmente alla Versione 1.

### Autenticazione

La chiave API è l'unica credenziale per accedere all'API di web scraping. Ogni servizio Cleariflow richiede una chiave univoca. Includete la chiave nel corpo JSON come `api_key`.

### URL base

```
https://scrape.cleariflow.com
```

### Rendering delle pagine

Le pagine vengono renderizzate in un vero browser headless. JavaScript viene eseguito completamente prima di restituire i contenuti. La protezione SSRF integrata blocca le richieste a localhost e alle reti IP private.

## Codici di risposta ed errore

In caso di errore, l'API restituisce risposte JSON strutturate con codici e descrizioni specifiche per una risoluzione efficace dei problemi.

| Codice | Tipo                  | Dettagli                                                                                               |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------ |
| 200    | OK                    | Tutto ha funzionato come previsto.                                                                     |
| 202    | Accepted              | Il job asincrono è stato accodato con successo.                                                        |
| 400    | Bad request           | Richiesta non valida — URL non valido, destinazione bloccata o payload malformato.                     |
| 401    | Unauthorized          | La richiesta non è stata accettata. Di solito per chiave API mancante o errata.                        |
| 422    | Quota reached         | La richiesta è stata interrotta per crediti API insufficienti. (Piani gratuiti)                        |
| 429    | Too many requests     | Raggiunto il limite di richieste al secondo. Nei piani gratuiti il limite è di 1 richiesta al secondo. |
| 500    | Internal server error | La richiesta non è stata completata a causa di un errore lato server.                                  |