Ingest

POST /v2/ingest convierte un sitio — o una lista explícita de URLs — en fragmentos listos para RAG y emite un único archivo JSONL que se carga directamente en JSONLoader de LangChain, SimpleDirectoryReader de LlamaIndex o una importación masiva a una base de datos vectorial. Reemplaza la pila de dos pasos que de otro modo tendrías que construir: Firecrawl /crawl para descubrir y extraer, más tu propio fragmentador para trocear el Markdown. EnConvert hace el descubrimiento, el renderizado en Chrome headless, el fragmentado consciente de encabezados y el ensamblado del JSONL en un solo trabajo.

Esta es la llamada útil más pequeña. Rastrea un sitio y fragmenta cada página que descubre:

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 respuesta es el registro del trabajo, devuelto con 202 Accepted. Observa que el estado es queued, y output_url está ausente hasta que el trabajo se 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 es siempre asíncrono. Cada página se renderiza en un navegador real, lo que tarda entre 10 y 30 segundos por URL — muy por encima de la ventana de petición de 300 segundos para cualquier trabajo no trivial. Por eso POST responde 202 con un job_id, y un worker local del droplet drena el trabajo fuera de banda. Sondeas GET /v2/ingest/{job_id} para ver el progreso, o registras un webhook_url para que te avisen cuando termine.

Vale la pena señalarlo de entrada. /v2/ingest es un endpoint V2 con su propio contador de cuota, ingest_pages. Los planes de conversión V1 no incluyen ninguna asignación de ingest — necesitas un plan que incluya V2 para llamarlo. Se factura una página por cada URL cuya etapa de renderizado, fragmentado y JSONL se complete; las páginas que fallan o se omiten no se facturan. Consulta la página de precios para ver las asignaciones por nivel, y la visión general de V2 para saber en qué se diferencian los contadores de V2 de las conversiones V1.

Endpoints

Content-Type: application/json en cada POST.

Authentication

Autentícate con una clave privada en el encabezado X-API-Key para las llamadas servidor a servidor. Esta es la vía que usan los ejemplos de abajo.

X-API-Key: sk_live_your_private_key

Las claves públicas con un token bearer JWT también funcionan, usando el mismo flujo que cualquier otro endpoint — genera un token con tu clave pk_, luego envíalo como Authorization: Bearer <token>. El flujo completo, incluido el bloqueo de dominio y la renovación del token, está en la guía de autenticación.

Cada clave de API lleva una lista de permitidos de endpoints autorizados. Si /v2/ingest no está en la lista de la clave, la petición se rechaza con 403. Una clave restringida a /v2/ingest aún alcanza los trabajos que creó — GET y DELETE /v2/ingest/{job_id} y POST /v2/ingest/{job_id}/retry-webhook siempre se permiten para un job_id (la forma ing_… se compara explícitamente). El endpoint de lista estático y las dos rutas de gestión de webhook-secret no heredan esa excepción; requieren un token de alcance más amplio o de dashboard.

How ingest works

Un trabajo recorre cinco fases, todas duraderas y a prueba de reinicios. Si el proceso del worker se reinicia a mitad de un trabajo, el trabajo se vuelve a encolar al arrancar y se reanuda desde la página en la que se detuvo — las páginas ya completadas conservan su salida preparada y nunca se vuelven a renderizar ni a facturar.

1. Queue. POST valida la petición, ejecuta una comprobación rápida de cuota units=1 (el plan tiene ingest habilitado y algo de margen mensual), inserta la fila del trabajo y responde 202. No se persiste nada si la compuerta de cuota falla — un 402 no deja ninguna fila atrás.
2. Discover. Para los modos sitemap y crawl el worker ejecuta el mismo pase de descubrimiento que el endpoint discover, limitado a max_pages, y aplica un filtro SSRF a la URL semilla. Para el modo urls la lista explícita se deduplica en orden; no se ejecuta ningún descubrimiento.
3. Render and chunk. Cada URL se renderiza a través del singleton compartido de Chrome headless — la misma canalización de renderizado detrás de el endpoint perceive — luego el HTML renderizado se convierte a fit-Markdown y se trocea con el fragmentador consciente de encabezados. Los renderizados se ejecutan secuencialmente, una página a la vez.
4. Stage. Los fragmentos de cada página se escriben en un objeto JSONL por página en el almacenamiento, indexado de forma determinista por (project, job, url). Esto es lo que hace barato un reinicio: un trabajo reanudado reutiliza las páginas preparadas en lugar de volver a renderizarlas.
5. Assemble. Una vez que todas las páginas están listas, los objetos por página se concatenan en el v2-ingest/{job_id}.jsonl final, los objetos de preparación se eliminan, el trabajo pasa a completed y — si se estableció un webhook_url — se dispara el webhook de finalización firmado.

El contador de cuota se vuelve a comprobar por página dentro del worker, no solo en el momento del envío. Un trabajo crawl cuyo número de páginas se desconoce de antemano se detiene limpiamente en tu tope mensual: las páginas ya renderizadas se facturan y se conservan, y las páginas restantes se marcan como skipped en lugar de gastar de más.

Los renderizados de ingest son sin credenciales por diseño. A diferencia de /v2/perceive, no acepta auth, cookies ni headers personalizados — no se persiste nada secreto para la reanudación duradera, por lo que el estado del trabajo en disco nunca lleva credenciales.

Request parameters

Source and mode

url y urls son mutuamente excluyentes — exactamente una fuente. El modo urls requiere urls; sitemap y crawl requieren una url semilla. Enviar la incorrecta para el modo es un 422.

Discovery (sitemap / crawl modes)

Estos se reenvían al pase de descubrimiento y se ignoran en el modo urls.

Rendering

Nota. Ingest no acepta auth, cookies ni headers. Si una página necesita credenciales para renderizarse, ingest es la herramienta equivocada — usa el endpoint perceive, que lleva toda la superficie de petición autenticada, para esa única página.

Chunking (chunk object)

El fragmentador divide en los encabezados #, ## y ### — cada fragmento pertenece a exactamente una sección y lleva su ruta de encabezados completa. Los encabezados más profundos (####–######) permanecen en línea como contenido. Los bloques de código entre vallas y las tablas de Markdown nunca se dividen, incluso cuando un solo bloque supera max_words; los elementos de lista se dividen entre elementos, nunca a mitad de un elemento.

Webhook

Response

POST, GET /v2/ingest/{job_id} y DELETE devuelven todos el mismo objeto IngestJobResponse.

Nota. POST y el GET/DELETE por trabajo usan response_model_exclude_none, por lo que los campos que aún son null (como output_url antes de completarse) se omiten del JSON en lugar de enviarse como null.

The JSONL record shape

El archivo final es JSON delimitado por saltos de línea. Cada línea es un fragmento:

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

El archivo es UTF-8, escrito con ensure_ascii=false, por lo que el unicode se mantiene legible. Como content es una cadena de nivel superior y metadata es un objeto hermano, el mismo archivo se carga con JSONLoader(content_key="content", json_lines=True) de LangChain, SimpleDirectoryReader de LlamaIndex y cualquier importación a base de datos vectorial orientada a líneas sin reestructurarse.

Job lifecycle and polling

Un trabajo se mueve a través de estos estados:

queued → discovering → processing → completed | failed | canceled

Sondea el estado con el GET por trabajo. Es de solo lectura — no consume cuota y vuelve a firmar el output_url a partir de la clave de objeto almacenada en cada llamada:

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

Un job_id desconocido, o uno que pertenece a otro proyecto, devuelve 404 — la existencia nunca se filtra entre proyectos.

Listing jobs

GET /v2/ingest devuelve los trabajos de este proyecto del más nuevo al más antiguo, con los parámetros de consulta skip y limit. limit tiene un valor predeterminado de 20 y un tope de 100. La respuesta lleva una bandera has_more en lugar de un recuento total:

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
}

Las filas de la lista reducen webhook_url a un booleano webhook_configured — la lista nunca devuelve el endpoint en bruto a la tabla.

Canceling a job

DELETE /v2/ingest/{job_id} establece el estado del trabajo a canceled. El worker lee ese estado entre páginas y se detiene sin ensamblar la salida. La cancelación es idempotente y a prueba de carreras: si el ensamblado ya se confirmó, el DELETE no coincide con nada y el trabajo se devuelve sin cambios como completed — un trabajo terminado nunca se revierte a canceled.

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

Completion webhooks

Establece webhook_url en el POST y EnConvert envía un único POST firmado con HMAC cuando el trabajo se completa. La carga útil es JSON compacto y ordenado por clave:

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

La entrega se reintenta hasta tres veces después del primer intento, con retardos de back-off de 1, 4 y 16 segundos — cuatro POST en el peor caso. Cada intento se vuelve a firmar con una marca de tiempo nueva, por lo que una cadena de reintentos lenta nunca se desfasa más allá de la ventana de frescura del consumidor. Una respuesta 2xx es éxito; un endpoint muerto se registra como una no entrega (y genera una alerta en el dashboard), nunca hunde un trabajo que por lo demás está completado.

El webhook_url recibe el filtro SSRF en el momento de la entrega, no en el del envío. Una URL que resuelve a una dirección privada, de loopback o de metadatos se almacena de forma inerte y solo se rechaza cuando EnConvert intenta hacer POST a ella.

Verifying the signature

Cada entrega lleva dos encabezados:

La entrada de firma es la marca de tiempo, un . literal, y luego el cuerpo en bruto de la petición. Vincular la marca de tiempo al MAC significa que un consumidor que rechaza marcas de tiempo obsoletas obtiene protección contra repetición gratis — la ventana de frescura predeterminada es de 300 segundos. Verifica en tu 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)

Managing the signing secret

GET /v2/ingest/webhook-secret revela el secreto del proyecto (creándolo en la primera llamada) junto con los nombres de encabezado y la tolerancia que necesita tu consumidor. Es sensible y se expone solo a través del canal autenticado del 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 emite un nuevo secreto y establece rotated a true. Toda firma calculada con el secreto anterior deja de verificarse en el momento en que la rotación se confirma — rota tras una fuga sospechada, luego actualiza tu consumidor.

Re-delivering a webhook

Si tu endpoint estaba caído cuando el trabajo terminó, POST /v2/ingest/{job_id}/retry-webhook vuelve a firmar y reenvía por POST con la misma política de reintentos:

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

Devuelve 404 para un job_id desconocido o ajeno, 400 cuando no hay webhook_url configurado (o la URL almacenada ahora resuelve a una dirección privada/interna), y 409 cuando el trabajo no ha alcanzado completed.

Code examples

curl — explicit URL list

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 with chunking and a 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 — submit, poll, 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 — submit and poll

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

El ingest de V2 se mide con su propio contador, ingest_pages — separado de las conversiones V1 y de los demás contadores de V2. Se factura una página por cada URL cuya etapa de renderizado, fragmentado y JSONL se completa; las páginas que fallan o se omiten no se facturan.

La comprobación en el momento del envío es una compuerta rápida units=1: tu plan debe tener ingest habilitado, con algo de margen mensual. El verdadero limitador del gasto es la comprobación por página dentro del worker — un trabajo crawl se detiene limpiamente en tu tope mensual y marca las páginas restantes como skipped en lugar de excederlo.

MAX_PAGES_PER_JOB (1.000) es un techo por petición que acota un solo trabajo; no es tu asignación mensual. La cuota mensual de ingest_pages es el verdadero limitador del gasto. Las cifras actuales por nivel están en la página de precios; consulta también cómo se miden las operaciones de perceive para el contador hermano de V2.

Error responses

Un fallo de renderizado a nivel de página no hace fallar la petición ni el trabajo — incrementa pages_failed, deja el error de la página en su propia fila, y el trabajo continúa. Un trabajo solo falla cuando se rechaza el descubrimiento o cuando todas las páginas fallan o se omiten. La referencia completa de códigos de estado está en la guía de códigos de error.

Limits