POST /v2/documents/process

Process documents

Ingests one or more sources — uploaded files, YouTube videos, web pages — extracts text, chunks it, embeds it, and indexes it into the vector store. The returned ids are usable in POST /v2/documents/query for retrieval-augmented question answering.

Unlike POST /v2/courses/generate-from-files, this endpoint only ingests — it doesn’t generate a course on top.

Request

Headers

Header	Required	Notes
`X-API-Key`	yes
`X-External-User-Id`	yes (or `X-User-Id`)	Identifies the owner of the indexed docs
`Content-Type`	yes	`multipart/form-data; boundary=…`

Form fields

files file[]

Files to ingest. Supported: PDF, DOCX, PPTX, HTML, PNG, JPG.

youtube_urls string

JSON array of YouTube URLs to transcribe and index.

web_urls string

JSON array of web page URLs to fetch, clean, and index.

space_id string

Optional logical grouping (a “space”). Documents in the same space can be queried together via space_id on the query endpoint.

Example

curl -X POST "https://api.nuton.app/v2/documents/process" \
  -H "X-API-Key: $NUTON_KEY" \
  -H "X-External-User-Id: alice@example.com" \
  -F "files=@whitepaper.pdf" \
  -F "youtube_urls=[\"https://youtu.be/kwSVtQ7dziU\"]" \
  -F "web_urls=[\"https://example.com/post\"]" \
  -F "space_id=q2-research"

Returns

{
  "documents": [
    {
      "id": "d_01HW0XYZ…",
      "filename": "whitepaper.pdf",
      "source_type": "file",
      "status": "ready",
      "chunk_count": 87
    },
    {
      "id": "d_01HW0XZA…",
      "filename": "https://youtu.be/kwSVtQ7dziU",
      "source_type": "youtube",
      "status": "ready",
      "chunk_count": 42
    },
    {
      "id": "d_01HW0XZB…",
      "filename": "https://example.com/post",
      "source_type": "web",
      "status": "error",
      "error": "Robots.txt disallows automated fetching."
    }
  ],
  "count": 3,
  "ready": 2,
  "errored": 1
}

Each source is processed in parallel; partial failures are reported per-document rather than failing the entire request.

For long YouTube videos and large PDFs, processing can take 30–60s. The response only returns once every source has either succeeded (status: "ready") or hit an unrecoverable error.

Errors

413 — Combined upload exceeds 500MB.
415 — Unsupported file format.
422 — Malformed youtube_urls / web_urls JSON.