---
title: "Ingest"
method: POST
path: "/v2/ingest"
tags: ["v2", "v2-ingest"]
---

# Ingest

`POST /v2/ingest`

## Request

- Base URL: `https://api.enconvert.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.enconvert.com/v2/ingest`
- Auth: none declared

Create an ingest job and enqueue it (202 + job_id).

Gate order matters: nothing is persisted until the quota gate passes — a
402 leaves zero rows behind. SSRF screening runs in the worker (the seed
via discover_flow, each page via render_html), so submit stays instant.

## Headers

- `X-API-Key` string, nullable
- `authorization` string, nullable

## Request body

- IngestRequest: One /v2/ingest job request (plan section 4 / section 8 Task H.7).
  - `mode` 'urls' | 'sitemap' | 'crawl' | 'files'
  - `url` string, nullable: Seed URL for sitemap/crawl mode (the site to ingest).
  - `urls` string[], nullable: Explicit URLs to ingest (urls mode). Mutually exclusive with url.
  - `max_pages` integer: Cap on URLs discovered AND ingested in sitemap/crawl mode.
  - `max_depth` integer
  - `same_domain_only` boolean
  - `include_patterns` string[]
  - `exclude_patterns` string[]
  - `respect_robots` boolean
  - `wait_for` string, nullable
  - `wait_timeout_ms` integer
  - `only_main_content` boolean: When true (default), each page's markdown strips site chrome (navigation, header, footer, sidebars, cookie banners, hidden nodes) behind a fidelity guard that falls back to the full page when stripping would remove too much real content. When false, the full page is chunked as-is.
  - `truncate_data_arrays` boolean, nullable: Collapse long runs of numeric literals (raw embedding vectors, tensor dumps in notebook output cells) to a leading sample plus a count. Unset (the default) follows only_main_content.
  - `chunk` ChunkOptions: Heading-aware chunker parameters (bounds mirror chunking.semantic).
    - `max_words` integer: Soft cap on words per chunk. Code blocks and tables stay atomic and may exceed this.
    - `sentence_overlap` integer: Sentences repeated between consecutive prose chunks of the same section (0 disables overlap).
  - `webhook_url` string, nullable

## Response `202`

Successful Response

- IngestJobResponse: Lifecycle view of one ingest job (POST 202, GET, DELETE all share it).
  - `job_id` string, required
  - `status` 'queued' | 'discovering' | 'processing' | 'completed' | 'failed' | 'canceled', required
  - `mode` 'urls' | 'sitemap' | 'crawl' | 'files', required
  - `pages_discovered` integer
  - `pages_found` integer, nullable: Unique eligible URLs discovery yielded BEFORE the max_pages cap (sitemap: true unique count; crawl: bounded by the crawl budget, so a lower bound). Absent for explicit-urls jobs and jobs created before migration 026.
  - `discovery_truncated` boolean: True when discovery found more unique URLs than max_pages allowed the job to enqueue.
  - `pages_processed` integer
  - `pages_failed` integer
  - `total_chunks` integer
  - `output_url` string, nullable: Signed URL to the final JSONL; present once completed.
  - `error_message` string, nullable
  - `webhook_url` string, nullable: Completion-webhook target registered for this job, if any.
  - `webhook_delivered` boolean: True once the signed completion webhook got a 2xx (H.8).
  - `created_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `warnings` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/enconvert/apis/conversion-api.md) · [All operations](https://skmtc.dev/enconvert/apis/conversion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/enconvert/apis/conversion-api/revisions/b8c820393569?raw)