---
title: "Ingest"
method: POST
path: "/api/kb/ingest"
tags: ["kb"]
---

# Ingest

`POST /api/kb/ingest`

Upload and ingest a document into the knowledge base.

Args:
    collection: Target collection name. If not provided, uses file name.
    file: The document file to upload and process.
    parse_method: Parser used during ingestion.
    chunk_strategy: Strategy for chunking the document.
    chunk_size: Target chunk size in characters.
    chunk_overlap: Overlap between consecutive chunks.
    separators: Optional JSON array of custom chunk separators (recursive only).
    embedding_model_id: Embedding model ID from model hub.
    embedding_batch_size: Batch size for embedding operations.
    max_retries: Maximum retry attempts for failures.
    retry_delay: Delay between retry attempts in seconds.

## Response `200`

Successful Response

- IngestionResult — Structured response for the document ingestion pipeline.
  - `status` string, required — Pipeline status: success|error|partial
  - `doc_id` string, nullable — Document identifier produced by register_document
  - `parse_hash` string, nullable — Parse hash produced during parse_document step
  - `chunk_count` integer — Number of chunks created; must be non-negative
  - `embedding_count` integer — Number of embeddings generated; must be non-negative
  - `vector_count` integer — Number of vectors written to storage; must be non-negative
  - `completed_steps` IngestionStepResult[] — List of successfully completed steps
    - `name` string, required — Step identifier
    - `metadata` object — Additional metadata captured for the step
  - `failed_step` string, nullable — Pipeline step where failure occurred, if any
  - `message` string, required — Human-readable summary of pipeline result
  - `warnings` string[] — Non-fatal warnings encountered
  - `file_id` string, nullable — Uploaded file ID for preview/download via /api/files (when ingest registers the file)

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/xorbitsai/apis/xagent.md) · [All operations](https://skmtc.net/xorbitsai/apis/xagent/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xorbitsai/xagent/revisions/33e4ba4936ad/schema)