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

# Ingest Cloud

`POST /api/kb/ingest-cloud`

Ingest files from cloud storage.

## Request body

- CloudIngestRequest
  - `files` CloudFile[], required
    - `provider` string, required
    - `fileId` string, required
    - `fileName` string, required
  - `collection` string, required
  - `parse_method` 'default' | 'pypdf' | 'pdfplumber' | 'unstructured' | 'pymupdf' | 'deepdoc' — Available parsing methods
  - `chunk_strategy` 'recursive' | 'fixed_size' | 'markdown' — Available chunk strategies
  - `chunk_size` integer, nullable
  - `chunk_overlap` integer, nullable
  - `separators` string[], nullable
  - `embedding_model_id` string
  - `embedding_batch_size` integer, nullable
  - `max_retries` integer, nullable
  - `retry_delay` number, nullable

## Response `200`

Successful Response

- IngestionResult[]
  - `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)