Ingest

POST /v2/ingest verwandelt eine Website — oder eine explizite Liste von URLs — in RAG-fertige Chunks und erzeugt eine einzige JSONL-Datei, die sich direkt in LangChain JSONLoader, LlamaIndex SimpleDirectoryReader oder einen Vektor-DB-Bulk-Import laden lässt. Sie ersetzt den zweistufigen Stack, den du sonst bauen müsstest: Firecrawl /crawl zum Entdecken und Scrapen, plus deinen eigenen Chunker, um das Markdown zu zerlegen. EnConvert erledigt die Entdeckung, das Headless-Chrome-Rendering, das überschriftenbewusste Chunking und das Zusammensetzen der JSONL in einem Job.

Hier ist der kleinste sinnvolle Aufruf. Crawle eine Website und chunke jede Seite, die sie entdeckt:

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

Die Antwort ist der Job-Datensatz, zurückgegeben mit 202 Accepted. Beachte, dass der Status queued ist und output_url fehlt, bis der Job abgeschlossen ist:

{
    "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 ist immer asynchron. Jede Seite wird in einem echten Browser gerendert, was 10–30 Sekunden pro URL dauert — weit jenseits des 300-Sekunden-Request-Fensters für jeden nicht-trivialen Job. Also antwortet POST mit 202 und einer job_id, und ein droplet-lokaler Worker arbeitet den Job außerhalb des Request-Pfads ab. Du pollst GET /v2/ingest/{job_id} für den Fortschritt oder registrierst eine webhook_url, um benachrichtigt zu werden, wenn er fertig ist.

Gleich vorab erwähnenswert. /v2/ingest ist ein V2-Endpunkt mit seinem eigenen Quota-Zähler, ingest_pages. V1-Konvertierungspläne enthalten keine Ingest-Freimenge — du brauchst einen Plan mit V2-Inklusivleistungen, um ihn aufzurufen. Eine Seite wird für jede URL abgerechnet, deren Render-, Chunk- und JSONL-Stufe abschließt; Seiten, die fehlschlagen oder übersprungen werden, werden nicht abgerechnet. Siehe die Preis- seite für die Freimengen pro Tarif und die V2-Übersicht dazu, wie sich die V2-Zähler von V1-Konvertierungen unterscheiden.

Endpunkte

Content-Type: application/json bei jedem POST.

Authentifizierung

Authentifiziere dich mit einem privaten Schlüssel im X-API-Key-Header für Server-zu-Server-Aufrufe. Dies ist der Weg, den die folgenden Beispiele nutzen.

X-API-Key: sk_live_your_private_key

Öffentliche Schlüssel mit einem JWT-Bearer-Token funktionieren ebenfalls und nutzen denselben Ablauf wie jeder andere Endpunkt — erzeuge ein Token mit deinem pk_-Schlüssel und sende es dann als Authorization: Bearer <token>. Der vollständige Ablauf, einschließlich Domain- Locking und Token-Refresh, steht in der Authentifizierungsanleitung.

Jeder API-Schlüssel trägt eine Allowlist erlaubter Endpunkte. Wenn /v2/ingest nicht auf der Liste des Schlüssels steht, wird die Anfrage mit 403 abgelehnt. Ein Schlüssel, der auf /v2/ingest eingegrenzt ist, erreicht trotzdem die von ihm erstellten Jobs — GET und DELETE /v2/ingest/{job_id} sowie POST /v2/ingest/{job_id}/retry-webhook sind für eine job_id immer erlaubt (die ing_…-Form wird explizit gematcht). Der statische Listen-Endpunkt und die beiden webhook-secret-Verwaltungsrouten erben diesen Bypass nicht; sie erfordern ein breiteres oder dashboard-eingegrenztes Token.

So funktioniert Ingest

Ein Job durchläuft fünf Phasen, alle dauerhaft und neustartsicher. Wenn der Worker-Prozess mitten im Job neu startet, wird der Job beim Booten erneut eingereiht und nimmt bei der Seite wieder auf, bei der er stoppte — bereits abgeschlossene Seiten behalten ihre gestagete Ausgabe und werden nie erneut gerendert oder erneut abgerechnet.

1. Queue. POST validiert die Anfrage, führt eine schnelle units=1-Quota- Prüfung durch (Plan hat Ingest aktiviert und etwas monatlichen Spielraum), fügt den Job-Datensatz ein und antwortet mit 202. Es wird nichts persistiert, wenn das Quota-Gate fehlschlägt — ein 402 hinterlässt null Datensätze.
2. Discover. Für sitemap- und crawl-Modus führt der Worker denselben Entdeckungsdurchlauf wie der Discover-Endpunkt aus, gedeckelt auf max_pages, und prüft die Seed-URL per SSRF-Screening. Für urls-Modus wird die explizite Liste in Reihenfolge dedupliziert; es läuft keine Entdeckung.
3. Render und Chunk. Jede URL wird über das gemeinsame Headless- Chrome-Singleton gerendert — dieselbe Render-Pipeline hinter dem Perceive-Endpunkt — dann wird das gerenderte HTML in fit-Markdown konvertiert und vom überschriftenbewussten Chunker zerlegt. Renderings laufen sequenziell, eine Seite nach der anderen.
4. Stage. Die Chunks jeder Seite werden in ein JSONL-Objekt pro Seite im Speicher geschrieben, deterministisch verschlüsselt nach (project, job, url). Genau das macht einen Neustart günstig: Ein wiederaufgenommener Job nutzt gestagete Seiten erneut, statt sie neu zu rendern.
5. Assemble. Sobald jede Seite fertig ist, werden die Objekte pro Seite in die finale v2-ingest/{job_id}.jsonl aneinandergehängt, die Staging- Objekte werden gelöscht, der Job wechselt zu completed und — falls eine webhook_url gesetzt war — feuert der signierte Abschluss-Webhook.

Der Quota-Zähler wird pro Seite im Worker erneut geprüft, nicht nur zum Einreichungszeitpunkt. Ein crawl-Job, dessen Seitenanzahl im Voraus unbekannt ist, stoppt sauber an deiner monatlichen Obergrenze: Die bereits gerenderten Seiten werden abgerechnet und behalten, und die verbleibenden Seiten werden als skipped markiert, statt zu überziehen.

Ingest-Renderings sind prinzipbedingt credential-frei. Anders als /v2/perceive akzeptiert es kein auth, keine cookies und keine eigenen headers — nichts Geheimes wird für den dauerhaften Resume persistiert, sodass der Job-Status auf der Platte nie Credentials trägt.

Request-Parameter

Quelle und Modus

url und urls schließen sich gegenseitig aus — genau eine Quelle. urls-Modus erfordert urls; sitemap und crawl erfordern eine Seed-url. Den falschen für den Modus zu senden, ist ein 422.

Discovery (sitemap/crawl-Modi)

Diese werden an den Entdeckungsdurchlauf weitergeleitet und im urls-Modus ignoriert.

Rendering

Hinweis. Ingest akzeptiert kein auth, keine cookies und keine headers. Wenn eine Seite Credentials zum Rendern braucht, ist Ingest das falsche Werkzeug — nutze den Perceive-Endpunkt, der die volle authentifizierte Request-Oberfläche trägt, für diese eine Seite.

Chunking (chunk-Objekt)

Der Chunker teilt an #-, ##- und ###-Überschriften — jeder Chunk gehört zu genau einem Abschnitt und trägt seinen vollständigen Überschriftenpfad. Tiefere Überschriften (####–######) bleiben inline als Inhalt. Eingezäunte Code-Blöcke und Markdown-Tabellen werden nie geteilt, selbst wenn ein einzelner Block max_words überschreitet; Listeneinträge teilen sich zwischen Einträgen, nie mitten im Eintrag.

Webhook

Response

POST, GET /v2/ingest/{job_id} und DELETE geben alle dasselbe IngestJobResponse-Objekt zurück.

Hinweis. POST und das GET/DELETE pro Job nutzen response_model_exclude_none, sodass Felder, die noch null sind (wie output_url vor dem Abschluss), aus dem JSON ausgelassen statt als null gesendet werden.

Die Form des JSONL-Datensatzes

Die finale Datei ist zeilengetrenntes JSON. Jede Zeile ist ein 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}}

Die Datei ist UTF-8, geschrieben mit ensure_ascii=false, sodass Unicode lesbar bleibt. Da content ein String auf oberster Ebene und metadata ein Geschwister-Objekt ist, lädt dieselbe Datei durch LangChain JSONLoader(content_key="content", json_lines=True), LlamaIndex SimpleDirectoryReader und jeden zeilenorientierten Vektor-DB-Import ohne Umformen.

Job-Lebenszyklus und Polling

Ein Job durchläuft diese Zustände:

queued → discovering → processing → completed | failed | canceled

Polle den Status mit dem GET pro Job. Das ist nur lesend — es verbraucht keine Quota und signiert die output_url bei jedem Aufruf aus dem gespeicherten Objekt-Schlüssel neu:

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

Eine unbekannte job_id oder eine, die einem anderen Projekt gehört, gibt 404 zurück — Existenz wird nie über Projekte hinweg preisgegeben.

Jobs auflisten

GET /v2/ingest gibt die Jobs dieses Projekts neueste-zuerst zurück, mit skip- und limit-Query-Parametern. limit ist standardmäßig 20 und auf 100 gedeckelt. Die Antwort trägt ein has_more-Flag statt einer Gesamtanzahl:

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
}

Die Listenzeilen reduzieren webhook_url auf einen webhook_configured-Boolean — die Liste gibt den rohen Endpunkt nie in die Tabelle zurück.

Einen Job abbrechen

DELETE /v2/ingest/{job_id} setzt den Status des Jobs auf canceled. Der Worker liest diesen Status zwischen Seiten und stoppt, ohne Ausgabe zusammenzusetzen. Der Abbruch ist idempotent und race-sicher: Wenn das Zusammensetzen bereits committed ist, matcht das DELETE nichts, und der Job wird unverändert als completed zurückgegeben — ein fertiger Job wird nie auf canceled zurückgesetzt.

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

Abschluss-Webhooks

Setze webhook_url beim POST, und EnConvert sendet einen HMAC-signierten POST, wenn der Job abschließt. Die Payload ist kompaktes, nach Schlüsseln sortiertes JSON:

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

Die Zustellung versucht es nach dem ersten Versuch bis zu dreimal erneut, mit Back-off- Verzögerungen von 1, 4 und 16 Sekunden — vier POSTs im schlimmsten Fall. Jeder Versuch wird mit einem frischen Zeitstempel neu signiert, sodass eine langsame Retry-Kette nie über das Frische-Fenster des Konsumenten hinaus driftet. Eine 2xx-Antwort ist ein Erfolg; ein toter Endpunkt wird als Nicht-Zustellung erfasst (und löst eine Dashboard-Warnung aus), er versenkt einen ansonsten abgeschlossenen Job nie.

Die webhook_url wird zum Zustellzeitpunkt per SSRF gescreent, nicht beim Einreichen. Eine URL, die auf eine private, Loopback- oder Metadaten-Adresse auflöst, wird inert gespeichert und erst abgelehnt, wenn EnConvert versucht, an sie zu POSTen.

Die Signatur verifizieren

Jede Zustellung trägt zwei Header:

Der Signing-Input ist der Zeitstempel, ein literales ., dann der rohe Request- Body. Den Zeitstempel in den MAC zu binden bedeutet, dass ein Konsument, der veraltete Zeitstempel ablehnt, Replay-Schutz gratis erhält — das Standard-Frische- Fenster ist 300 Sekunden. Verifiziere in deinem 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)

Das Signing-Secret verwalten

GET /v2/ingest/webhook-secret zeigt das Secret des Projekts (und erstellt es beim ersten Aufruf) zusammen mit den Header-Namen und der Toleranz, die dein Konsument braucht. Es ist sensibel und wird nur über den authentifizierten Dashboard-Kanal preisgegeben:

{
    "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 gibt ein neues Secret aus und setzt rotated auf true. Jede mit dem vorherigen Secret berechnete Signatur verifiziert in dem Moment nicht mehr, in dem die Rotation committet — rotiere nach einem vermuteten Leak und aktualisiere dann deinen Konsumenten.

Einen Webhook erneut zustellen

Wenn dein Endpunkt ausgefallen war, als der Job fertig wurde, signiert und sendet POST /v2/ingest/{job_id}/retry-webhook mit derselben Retry-Policy erneut per POST:

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)."
}

Es gibt 404 für eine unbekannte oder fremde job_id zurück, 400, wenn keine webhook_url konfiguriert ist (oder die gespeicherte URL nun auf eine private/interne Adresse auflöst), und 409, wenn der Job completed nicht erreicht hat.

Code-Beispiele

curl — explizite URL-Liste

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 mit Chunking und einem 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 — einreichen, pollen, herunterladen

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 — einreichen und pollen

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]);
}

Plan-Gating

V2-Ingest wird über seinen eigenen Zähler ingest_pages gemessen — getrennt von V1- Konvertierungen und von den anderen V2-Zählern. Eine Seite wird für jede URL abgerechnet, deren Render-, Chunk- und JSONL-Stufe abschließt; Seiten, die fehlschlagen oder übersprungen werden, werden nicht abgerechnet.

Die Prüfung zum Einreichungszeitpunkt ist ein schnelles units=1-Gate: Dein Plan muss Ingest aktiviert haben, mit etwas monatlichem Spielraum. Der eigentliche Ausgaben-Begrenzer ist die pro-Seite-Prüfung im Worker — ein crawl-Job stoppt sauber an deiner monatlichen Obergrenze und markiert die verbleibenden Seiten als skipped, statt sie zu überlaufen.

MAX_PAGES_PER_JOB (1.000) ist eine Obergrenze pro Request, die einen einzelnen Job begrenzt; es ist nicht deine monatliche Freimenge. Die monatliche ingest_pages-Quota ist der eigentliche Ausgaben-Begrenzer. Aktuelle Zahlen pro Tarif stehen auf der Preisseite; siehe auch wie Perceive-Operationen gemessen werden für den verwandten V2-Zähler.

Fehler-Responses

Ein Render-Fehler auf Seitenebene lässt die Anfrage oder den Job nicht fehlschlagen — er erhöht pages_failed, schreibt den Fehler der Seite in ihre eigene Zeile, und der Job läuft weiter. Ein Job fails nur, wenn die Entdeckung abgelehnt wird oder jede Seite fehlschlägt oder übersprungen wird. Die vollständige Statuscode-Referenz steht in der Fehlercodes-Anleitung.

Limits