Ingest

POST /v2/ingest trasforma un sito — o un elenco esplicito di URL — in chunk pronti per il RAG ed emette un solo file JSONL che si carica direttamente in LangChain JSONLoader, LlamaIndex SimpleDirectoryReader o un import massivo in un vector-DB. Sostituisce lo stack in due fasi che altrimenti dovresti costruire: Firecrawl /crawl per scoprire ed estrarre i contenuti, più il tuo chunker per affettare il Markdown. EnConvert si occupa della discovery, del rendering headless-Chrome, del chunking consapevole delle intestazioni e dell'assemblaggio del JSONL in un solo job.

Ecco la chiamata utile più piccola. Fai il crawl di un sito e chunka ogni pagina che scopre:

curl -X POST https://api.enconvert.com/v2/ingest \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "crawl",
    "url": "https://example.com/docs"
  }'

La risposta è il record del job, restituito con 202 Accepted. Nota che lo status è queued, e output_url è assente finché il job non si completa:

{
    "job_id": "ing_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "queued",
    "mode": "crawl",
    "pages_discovered": 0,
    "pages_processed": 0,
    "pages_failed": 0,
    "total_chunks": 0,
    "webhook_delivered": false,
    "created_at": "2026-06-24T09:14:02.118Z"
}

Ingest è sempre asincrono. Ogni pagina viene renderizzata in un browser reale, il che richiede 10–30 secondi per URL — ben oltre la finestra di richiesta di 300 secondi per qualsiasi job non banale. Quindi POST risponde 202 con un job_id, e un worker locale sul droplet svuota il job fuori banda. Fai il polling di GET /v2/ingest/{job_id} per i progressi, oppure registra un webhook_url per essere avvisato al completamento.

Vale la pena segnalarlo subito. /v2/ingest è un endpoint V2 con il proprio contatore di quota, ingest_pages. I piani di conversione V1 non includono alcun budget di ingest — serve un piano che includa V2 per chiamarlo. Viene addebitata una pagina per ogni URL il cui stage di render, chunk e JSONL si completa; le pagine che falliscono o vengono saltate non vengono addebitate. Vedi la pagina dei prezzi per i budget per livello, e la panoramica V2 per come i contatori V2 differiscono dalle conversioni V1.

Endpoints

Content-Type: application/json su ogni POST.

Autenticazione

Autenticati con una chiave privata nell'header X-API-Key per le chiamate server-to-server. Questo è il percorso usato dagli esempi seguenti.

X-API-Key: sk_live_your_private_key

Funzionano anche le chiavi pubbliche con un token bearer JWT, usando lo stesso flusso di ogni altro endpoint — genera un token con la tua chiave pk_, poi invialo come Authorization: Bearer <token>. Il flusso completo, inclusi il domain locking e il refresh del token, è ne la guida all'autenticazione.

Ogni chiave API porta con sé una allowlist di endpoint consentiti. Se /v2/ingest non è nell'elenco della chiave, la richiesta viene rifiutata con 403. Una chiave con scope su /v2/ingest raggiunge comunque i job che ha creato — GET e DELETE /v2/ingest/{job_id} e POST /v2/ingest/{job_id}/retry-webhook sono sempre consentiti per un job_id (la forma ing_… viene confrontata in modo esplicito). L'endpoint di elenco statico e le due route di gestione webhook-secret non ereditano quel bypass; richiedono un token più ampio o con scope dashboard.

Come funziona l'ingest

Un job attraversa cinque fasi, tutte durevoli e a prova di riavvio. Se il processo worker si riavvia a metà job, il job viene ri-accodato all'avvio e riprende dalla pagina su cui si era fermato — le pagine già completate mantengono il loro output in staging e non vengono mai ri-renderizzate né ri-addebitate.

1. Queue. POST valida la richiesta, esegue un veloce controllo di quota units=1 (il piano ha ingest abilitato e un po' di margine mensile), inserisce la riga del job e risponde 202. Nulla viene persistito se il gate di quota fallisce — un 402 non lascia alcuna riga dietro di sé.
2. Discover. Per le modalità sitemap e crawl il worker esegue lo stesso passaggio di discovery di l'endpoint discover, limitato a max_pages, e applica lo screening SSRF all'URL seed. Per la modalità urls l'elenco esplicito viene deduplicato nell'ordine dato; nessuna discovery viene eseguita.
3. Render and chunk. Ogni URL viene renderizzato attraverso il singleton headless Chrome condiviso — la stessa pipeline di rendering dietro l'endpoint perceive — poi l'HTML renderizzato viene convertito in fit-Markdown e affettato dal chunker consapevole delle intestazioni. I rendering vengono eseguiti in sequenza, una pagina alla volta.
4. Stage. I chunk di ogni pagina vengono scritti in un oggetto JSONL per pagina nello storage, con chiave deterministica basata su (project, job, url). È questo che rende economico un riavvio: un job ripreso riutilizza le pagine in staging invece di ri-renderizzarle.
5. Assemble. Una volta che ogni pagina è pronta, gli oggetti per pagina vengono concatenati nel v2-ingest/{job_id}.jsonl finale, gli oggetti di staging vengono eliminati, il job passa a completed e — se era impostato un webhook_url — scatta il webhook di completamento firmato.

Il contatore di quota viene ri-controllato per pagina dentro il worker, non solo al momento dell'invio. Un job crawl il cui conteggio di pagine è ignoto in partenza si ferma in modo pulito al tuo limite mensile: le pagine già renderizzate vengono addebitate e conservate, e le pagine rimanenti vengono marcate skipped invece di sforare la spesa.

I rendering di ingest sono privi di credenziali per progettazione. A differenza di /v2/perceive, non accetta auth, cookies o headers personalizzati — nulla di segreto viene persistito per il resume durevole, quindi lo stato del job su disco non porta mai con sé credenziali.

Parametri della richiesta

Sorgente e modalità

url e urls si escludono a vicenda — esattamente una sorgente. La modalità urls richiede urls; sitemap e crawl richiedono un url seed. Inviare quello sbagliato per la modalità è un 422.

Discovery (modalità sitemap / crawl)

Questi vengono inoltrati al passaggio di discovery e ignorati in modalità urls.

Rendering

Nota. Ingest non accetta auth, cookies o headers. Se una pagina ha bisogno di credenziali per essere renderizzata, ingest è lo strumento sbagliato — usa l'endpoint perceive, che porta con sé l'intera superficie di richiesta autenticata, per quella singola pagina.

Chunking (oggetto chunk)

Il chunker divide sulle intestazioni #, ## e ### — ogni chunk appartiene a esattamente una sezione e porta con sé il proprio percorso completo di intestazioni. Le intestazioni più profonde (####–######) restano inline come contenuto. I blocchi di codice recintati e le tabelle Markdown non vengono mai divisi, anche quando un singolo blocco supera max_words; gli elementi di lista si dividono tra le voci, mai a metà voce.

Webhook

Response

POST, GET /v2/ingest/{job_id} e DELETE restituiscono tutti lo stesso oggetto IngestJobResponse.

Nota. POST e il GET/DELETE per singolo job usano response_model_exclude_none, quindi i campi ancora null (come output_url prima del completamento) vengono omessi dal JSON anziché inviati come null.

La forma del record JSONL

Il file finale è JSON delimitato da newline. Ogni riga è un chunk:

{"id":"9f2b8c1ad4e5-0000","content":"Pricing is usage-based...","metadata":{"source_url":"https://example.com/pricing","title":"Pricing","headings_path":["Pricing","Plans"],"section":"Plans","word_count":118,"chunk_index":0}}

Il file è UTF-8, scritto con ensure_ascii=false, quindi l'unicode resta leggibile. Poiché content è una stringa di primo livello e metadata è un oggetto fratello, lo stesso file si carica tramite LangChain JSONLoader(content_key="content", json_lines=True), LlamaIndex SimpleDirectoryReader e qualsiasi import vector-DB orientato alle righe senza alcuna ristrutturazione.

Ciclo di vita del job e polling

Un job attraversa questi stati:

queued → discovering → processing → completed | failed | canceled

Fai il polling dello status con il GET per singolo job. È in sola lettura — non consuma quota e ri-firma l'output_url dalla chiave dell'oggetto memorizzato a ogni chiamata:

curl https://api.enconvert.com/v2/ingest/ing_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_live_your_private_key"

Un job_id sconosciuto, o uno che appartiene a un progetto diverso, restituisce 404 — l'esistenza non viene mai rivelata tra progetti.

Elenco dei job

GET /v2/ingest restituisce i job di questo progetto dal più recente, con i query param skip e limit. limit ha default 20 ed è limitato a 100. La risposta porta un flag has_more invece di un conteggio totale:

curl "https://api.enconvert.com/v2/ingest?skip=0&limit=20" \
  -H "X-API-Key: sk_live_your_private_key"

{
    "jobs": [
        {
            "job_id": "ing_3f9a...",
            "status": "completed",
            "mode": "crawl",
            "pages_discovered": 42,
            "pages_processed": 41,
            "pages_failed": 1,
            "total_chunks": 1187,
            "output_url": "https://spaces.example.com/...signed...",
            "webhook_configured": true,
            "webhook_delivered": true,
            "created_at": "2026-06-24T09:14:02.118Z",
            "completed_at": "2026-06-24T09:31:55.402Z"
        }
    ],
    "skip": 0,
    "limit": 20,
    "has_more": false
}

Le righe dell'elenco riducono webhook_url a un booleano webhook_configured — l'elenco non rimanda mai l'endpoint grezzo nella tabella.

Annullamento di un job

DELETE /v2/ingest/{job_id} imposta lo status del job a canceled. Il worker legge quello status tra una pagina e l'altra e si ferma senza assemblare l'output. L'annullamento è idempotente e a prova di race: se l'assemblaggio è già stato confermato, il DELETE non corrisponde a nulla e il job viene restituito invariato come completed — un job concluso non viene mai riportato indietro a canceled.

curl -X DELETE \
  https://api.enconvert.com/v2/ingest/ing_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_live_your_private_key"

Webhook di completamento

Imposta webhook_url sul POST ed EnConvert invia un POST firmato con HMAC quando il job si completa. Il payload è JSON compatto, con chiavi ordinate:

{"job_id":"ing_3f9a...","output_url":"https://spaces.example.com/...signed...","pages_processed":41,"status":"completed","total_chunks":1187}

La consegna ritenta fino a tre volte dopo il primo tentativo, con ritardi di back-off di 1, 4 e 16 secondi — quattro POST nel caso peggiore. Ogni tentativo viene ri-firmato con un timestamp fresco, così una catena di retry lenta non va mai oltre la finestra di freschezza del consumer. Una risposta 2xx è un successo; un endpoint morto viene registrato come mancata consegna (e fa scattare un alert nella dashboard), non affossa mai un job altrimenti completato.

Il webhook_url viene sottoposto a screening SSRF al momento della consegna, non all'invio. Un URL che risolve a un indirizzo privato, di loopback o di metadata viene memorizzato in modo inerte e rifiutato solo quando EnConvert prova a inviarci un POST.

Verifica della firma

Ogni consegna porta due header:

L'input di firma è il timestamp, un . letterale, poi il corpo grezzo della richiesta. Legare il timestamp nel MAC significa che un consumer che rifiuta i timestamp scaduti ottiene gratis la protezione dal replay — la finestra di freschezza di default è 300 secondi. Verifica nel tuo handler:

import hashlib
import hmac
import time

SECRET = "whsec_your_signing_secret"   # from GET /v2/ingest/webhook-secret
TOLERANCE_SECONDS = 300


def verify(raw_body: bytes, signature_header: str, timestamp_header: str) -> bool:
    if not signature_header or not timestamp_header:
        return False
    try:
        ts = int(timestamp_header)
    except ValueError:
        return False
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return False  # replayed or badly skewed clock

    provided = signature_header.removeprefix("sha256=")
    expected = hmac.new(
        SECRET.encode("utf-8"),
        f"{ts}.".encode("utf-8") + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, provided)

Gestione del segreto di firma

GET /v2/ingest/webhook-secret rivela il segreto del progetto (creandolo alla prima chiamata) insieme ai nomi degli header e alla tolleranza di cui il tuo consumer ha bisogno. È sensibile ed esposto solo sul canale autenticato della dashboard:

{
    "secret": "whsec_...",
    "signature_header": "X-Enconvert-Signature",
    "timestamp_header": "X-Enconvert-Timestamp",
    "signature_scheme": "sha256",
    "replay_tolerance_seconds": 300,
    "rotated": false
}

POST /v2/ingest/webhook-secret/rotate emette un nuovo segreto e imposta rotated a true. Ogni firma calcolata con il segreto precedente smette di verificarsi nel momento in cui la rotazione viene confermata — ruota dopo un sospetto leak, poi aggiorna il tuo consumer.

Riconsegna di un webhook

Se il tuo endpoint era giù quando il job è terminato, POST /v2/ingest/{job_id}/retry-webhook ri-firma e ri-invia in POST con la stessa policy di retry:

curl -X POST \
  https://api.enconvert.com/v2/ingest/ing_3f9a.../retry-webhook \
  -H "X-API-Key: sk_live_your_private_key"

{
    "job_id": "ing_3f9a...",
    "delivered": true,
    "attempts": 1,
    "status_code": 200,
    "detail": "Delivered (HTTP 200)."
}

Restituisce 404 per un job_id sconosciuto o estraneo, 400 quando nessun webhook_url è configurato (o l'URL memorizzato ora risolve a un indirizzo privato/interno), e 409 quando il job non ha raggiunto completed.

Esempi di codice

curl — elenco esplicito di URL

curl -X POST https://api.enconvert.com/v2/ingest \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "urls",
    "urls": [
      "https://example.com/docs/intro",
      "https://example.com/docs/quickstart",
      "https://example.com/docs/api"
    ]
  }'

curl — crawl con chunking e webhook

curl -X POST https://api.enconvert.com/v2/ingest \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "crawl",
    "url": "https://example.com/docs",
    "max_pages": 200,
    "max_depth": 3,
    "include_patterns": ["/docs/"],
    "chunk": {"max_words": 700, "sentence_overlap": 2},
    "webhook_url": "https://your-app.example.com/hooks/ingest"
  }'

Python — invio, polling, download

import time

import requests

BASE = "https://api.enconvert.com"
HEADERS = {"X-API-Key": "sk_live_your_private_key"}

# 1. Submit (always 202).
job = requests.post(
    f"{BASE}/v2/ingest",
    headers=HEADERS,
    json={"mode": "crawl", "url": "https://example.com/docs", "max_pages": 100},
).json()
job_id = job["job_id"]

# 2. Poll until terminal.
while True:
    job = requests.get(f"{BASE}/v2/ingest/{job_id}", headers=HEADERS).json()
    if job["status"] in ("completed", "failed", "canceled"):
        break
    time.sleep(5)

# 3. Download the JSONL from its signed URL.
if job["status"] == "completed":
    jsonl = requests.get(job["output_url"]).text
    print(f"{job['total_chunks']} chunks across "
          f"{job['pages_processed']} pages")
    print(jsonl.splitlines()[0])

Node.js — invio e polling

const BASE = "https://api.enconvert.com";
const HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "sk_live_your_private_key"
};

// 1. Submit.
const submit = await fetch(`${BASE}/v2/ingest`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({
        mode: "crawl",
        url: "https://example.com/docs",
        max_pages: 100
    })
});
let job = await submit.json();

// 2. Poll until terminal.
while (!["completed", "failed", "canceled"].includes(job.status)) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await fetch(`${BASE}/v2/ingest/${job.job_id}`, {
        headers: { "X-API-Key": HEADERS["X-API-Key"] }
    });
    job = await poll.json();
}

// 3. Download the JSONL.
if (job.status === "completed") {
    const jsonl = await fetch(job.output_url).then((r) => r.text());
    console.log(`${job.total_chunks} chunks`);
    console.log(jsonl.split("\n")[0]);
}

Gating del piano

L'ingest V2 è misurato dal proprio contatore, ingest_pages — separato dalle conversioni V1 e dagli altri contatori V2. Viene addebitata una pagina per ogni URL il cui stage di render, chunk e JSONL si completa; le pagine che falliscono o vengono saltate non vengono addebitate.

Il controllo al momento dell'invio è un veloce gate units=1: il tuo piano deve avere ingest abilitato, con un po' di margine mensile. Il vero limitatore di spesa è il controllo per pagina dentro il worker — un job crawl si ferma in modo pulito al tuo limite mensile e marca le pagine rimanenti skipped invece di sforarlo.

MAX_PAGES_PER_JOB (1.000) è un tetto per richiesta che delimita un singolo job; non è il tuo budget mensile. La quota mensile ingest_pages è il vero limitatore di spesa. I numeri attuali per livello sono su la pagina dei prezzi; vedi anche come vengono misurate le operazioni perceive per il contatore V2 gemello.

Risposte di errore

Un fallimento di render a livello di pagina non fa fallire la richiesta né il job — incrementa pages_failed, deposita l'errore della pagina nella sua riga e il job continua. Un job fails solo quando la discovery viene rifiutata oppure ogni pagina fallisce o viene saltata. Il riferimento completo dei codici di stato è ne la guida ai codici di errore.

Limiti