> ## 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.

# Scraping sincrono

> L'endpoint `scrape` avvia una sessione del browser, esegue JavaScript e restituisce HTML renderizzato in una singola richiesta sincrona.

## Per iniziare

### URL base

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

### Esempio di richiesta

```bash theme={"system"}
curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://example.com",
    "render": {
      "wait_until": "networkidle",
      "timeout_ms": 60000
    }
  }'
```

Questa richiesta riuscita restituisce l'HTML renderizzato della pagina e i metadati:

```json theme={"system"}
{
  "ok": true,
  "html": "<!DOCTYPE html><html>...</html>",
  "meta": {
    "elapsed_ms": 4521
  }
}
```

### Opzioni di rendering

L'oggetto `render` controlla come il browser carica la pagina prima di catturare l'HTML. Tutti i campi sono opzionali — se omessi, si applicano i default del server.

```json theme={"system"}
{
  "render": {
    "wait_until": "networkidle",
    "timeout_ms": 60000,
    "post_load_wait_ms": 2000,
    "ignore_https_errors": false
  }
}
```

| Campo | Tipo | Predefinito | Descrizione |
| - | - | - | - |
| `wait_until` | String | `domcontentloaded` | Quando considerare completata la navigazione. `domcontentloaded` per risultati più rapidi; `networkidle` se la pagina carica dati via XHR/fetch dopo l'HTML iniziale. |
| `timeout_ms` | Integer | `60000` | Tempo massimo in millisecondi per il caricamento. La richiesta fallisce se superato. |
| `post_load_wait_ms` | Integer | `0` | Ritardo aggiuntivo in millisecondi dopo `wait_until` prima di catturare l'HTML. Utile per animazioni, widget lazy-loaded o rendering client-side dopo `networkidle`. |
| `ignore_https_errors` | Boolean | `false` | Con `true`, ignora errori di certificato TLS sulla pagina di destinazione. |

Esempio per una pagina JavaScript-heavy che continua a recuperare dati dopo il caricamento:

```bash theme={"system"}
curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://quotes.toscrape.com/js/",
    "render": {
      "wait_until": "networkidle",
      "timeout_ms": 60000,
      "post_load_wait_ms": 1500,
      "ignore_https_errors": false
    }
  }'
```

### Opzioni risorse

L'oggetto `resources` controlla quali tipi di asset il browser carica durante lo scraping. Bloccare risorse pesanti accelera le richieste quando servono solo testo e struttura HTML.

```json theme={"system"}
{
  "resources": {
    "block": ["images", "fonts", "media"]
  }
}
```

| Valore | Blocca |
| - | - |
| `images` | Immagini (`<img>`, sfondi CSS, icone SVG caricate come immagini) |
| `fonts` | Web font |
| `media` | Stream video e audio |

Tutti i campi sono opzionali. Se `resources` è omesso, nessun tipo di risorsa viene bloccato, salvo default lato server nella deployment.

Esempio — scraping più veloce saltando immagini e font:

```bash theme={"system"}
curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://quotes.toscrape.com/",
    "resources": {
      "block": ["images", "fonts"]
    }
  }'
```

### Parametri della richiesta

**url** `String` *required*

L'URL di destinazione da scrapare. Deve essere un URL HTTP o HTTPS pubblico. Le richieste a localhost e IP privati sono bloccate dalla protezione SSRF.

**api\_key** `String` *required*

La tua chiave API univoca.

**session\_id** `String`

Identificatore di sessione opzionale per riutilizzare lo stato del browser (cookie, local storage) tra più richieste di scraping.

**fingerprint** `String`

Preset dell'impronta del browser. Valori supportati: `desktop_en_us`, `desktop_ru_ru`, `mobile_en_us`.

**render** `Object`

Opzioni di rendering per la sessione del browser.

**render.wait\_until** `String`

Quando considerare completata la navigazione. Valori: `domcontentloaded`, `networkidle`. Predefinito: `domcontentloaded`.

**render.timeout\_ms** `Integer`

Tempo massimo in millisecondi per attendere il caricamento della pagina. Predefinito: 60000.

**render.post\_load\_wait\_ms** `Integer`

Ritardo aggiuntivo in millisecondi dopo il caricamento prima di catturare i contenuti.

**render.ignore\_https\_errors** `Boolean`

Se `true`, ignora gli errori del certificato TLS della pagina di destinazione.

**resources** `Object`

Controlli sul caricamento delle risorse.

**resources.block** `Array`

Tipi di risorse da bloccare. Valori supportati: `images`, `fonts`, `media`.

**actions** `Array`

Elenco ordinato di azioni del browser da eseguire prima di catturare i contenuti. Ogni azione è un oggetto con un campo `type`.

**actions\[].type** `String` *required*

Tipo di azione. Valori supportati: `wait`, `wait_for`, `click`, `type`, `scroll`.

**actions\[].selector** `String`

Selettore CSS per le azioni `wait_for`, `click` o `type`.

**actions\[].text** `String`

Testo da digitare per l'azione `type`.

**actions\[].to** `String`

Destinazione dello scroll per l'azione `scroll` (es. `bottom`).

**actions\[].wait\_ms** `Integer`

Durata in millisecondi per l'azione `wait`.

**actions\[].timeout\_ms** `Integer`

Timeout in millisecondi per le azioni `wait_for`.

**cookies** `Array`

Cookie da iniettare prima della navigazione. Ogni oggetto cookie richiede `name` e `value`; campi opzionali: `domain`, `path`.

### Parametri della risposta

La risposta dell'API viene restituita in un [formato JSON](https://www.json.org/json-en.html) universale e leggero.

**ok** `Boolean`

Indica se lo scraping è stato completato con successo.

**html** `String`

L'HTML renderizzato della pagina.

**meta** `Object`

Metadati dello scraping, inclusi URL finale, codice di stato HTTP e durata.

**error** `Object`

Dettagli dell'errore quando `ok` è `false`.


## OpenAPI

````yaml openapi/scrape.json POST /v1/scrape
openapi: 3.0.3
info:
  title: Web Scraping API (Browser-as-a-Service)
  version: 1.0.0
  description: High-load browser scraping API backed by Camoufox workers.
servers:
  - url: https://scrape.cleariflow.com
    description: Production server
security: []
paths:
  /v1/scrape:
    post:
      summary: Synchronous scrape (Camoufox)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeRequest'
      responses:
        '200':
          description: Scrape result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Quota reached
        '429':
          description: Too many requests
        '500':
          description: Internal server error
components:
  schemas:
    ScrapeRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        api_key:
          type: string
          description: Your Cleariflow API key, passed in the JSON request body.
        session_id:
          type: string
        fingerprint:
          type: string
          description: Preset string (desktop_en_us|desktop_ru_ru|mobile_en_us|...)
        render:
          $ref: '#/components/schemas/RenderOptions'
        resources:
          $ref: '#/components/schemas/ResourceOptions'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
        artifacts:
          type: array
          items:
            type: string
            enum:
              - html
              - screenshot
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/Cookie'
    ScrapeResponse:
      type: object
      properties:
        ok:
          type: boolean
        html:
          type: string
        artifacts:
          type: object
          additionalProperties: true
        meta:
          type: object
          additionalProperties: true
        error:
          type: object
          additionalProperties: true
    RenderOptions:
      type: object
      properties:
        wait_until:
          type: string
          enum:
            - domcontentloaded
            - networkidle
        timeout_ms:
          type: integer
        post_load_wait_ms:
          type: integer
    ResourceOptions:
      type: object
      properties:
        block:
          type: array
          items:
            type: string
            enum:
              - images
              - fonts
              - media
    Action:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - wait
            - wait_for
            - click
            - type
            - scroll
        selector:
          type: string
        text:
          type: string
        to:
          type: string
        wait_ms:
          type: integer
        timeout_ms:
          type: integer
    Cookie:
      type: object
      required:
        - name
        - value
      properties:
        path:
          type: string
        value:
          type: string
        name:
          type: string
        domain:
          type: string

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.