# Upload files and ingest

Put files into a file-upload knowledge source from your application, start indexing when the upload did not, follow each document to completion and prove the content is searchable.

A file-upload knowledge source takes files over the API. The upload stores them as pending documents and, when it can, starts indexing at once; the ingest route processes anything still pending; the document route shows each file's progress; and a search proves the content is live.

**Who can use it:** anyone holding an API key with the **Documents** scope for the upload and document routes and the **Load knowledge graph** scope for ingest; the sources list needs **Knowledge search** or **Documents**. Ingest also requires the key's owner to be the source's creator or to manage its access. Creating a source and uploading into it also require the key's owner to be allowed to create knowledge sources.

## Prerequisites

- A file-upload knowledge source. Create it in the platform (**Knowledge Sources** in Studio, **Add Source**, then **File Upload**) or with `POST /public/v1/sources` using the `file_upload` connector type; the [File Upload connector](/knowledge/connectors/file-upload) page in the help centre lists what it accepts.
- Files of an accepted type, each within the size limit your administrator set for the tenant.

## Upload, index and follow

1. **Find the source id.** `GET /public/v1/sources` lists the tenant's sources; pick the one whose `connector_type` is `file_upload` and keep its `id`.

2. **Upload the files** as multipart form data in the `files` field, one part per file.

   ```bash
   curl -X POST "https://<your tenant host>/public/v1/sources/<source-id>/upload" \
     -H "Authorization: Bearer kapi_..." \
     -F "files=@quarterly-report.pdf" \
     -F "files=@vendor-policy.docx"
   ```

   The response lists what was stored under `uploaded` (each with its document `id`, `filename`, `size_bytes` and `content_type`), a `count`, any rejected files under `failed` with a `reason`, and two fields that tell you what happens next: `sync_started` says whether this request started the indexing run, and `sync_note` explains why not when it did not.

3. **Start indexing only if the upload did not.** When `sync_started` is true, indexing is already under way. When it is false and `sync_note` says a sync was already running, that run will index the new files. When the note says indexing could not be started, call ingest:

   ```bash
   curl -X POST "https://<your tenant host>/public/v1/sources/<source-id>/ingest" \
     -H "Authorization: Bearer kapi_..."
   ```

   A 202 with `status` `started` carries the `run_id`; a 200 with `no_pending_documents` means there was nothing to do; a 409 means a sync is already running and names its run when it can.

4. **Follow each document.** `GET /public/v1/documents/<doc-id>` returns the record: `processing_status` moves from `pending` through `processing` to `completed`, or ends as `failed` with `processing_error`, `empty` when no text could be indexed, or `access_denied`. `chunk_count` fills in as the document is indexed.

   ```python
   import time, requests

   BASE = "https://<your tenant host>/public/v1"
   HEADERS = {"Authorization": "Bearer kapi_..."}

   with open("quarterly-report.pdf", "rb") as f:
       up = requests.post(f"{BASE}/sources/<source-id>/upload", headers=HEADERS,
                          files=[("files", ("quarterly-report.pdf", f))]).json()
   if not up["sync_started"] and "could not be started" in (up.get("sync_note") or ""):
       requests.post(f"{BASE}/sources/<source-id>/ingest", headers=HEADERS)

   for doc in up["uploaded"]:
       while True:
           rec = requests.get(f"{BASE}/documents/{doc['id']}", headers=HEADERS).json()
           if rec["processing_status"] in ("completed", "failed", "empty", "access_denied"):
               print(doc["filename"], rec["processing_status"], rec.get("processing_error") or "")
               break
           time.sleep(5)
   ```

5. **Prove it.** Search with `source_ids` limited to the source and a question the file answers; the hit's `source` names the document. See [Search with citations](/developers/guides/search-with-citations).

## Verify

Each uploaded document reaches `completed` with a `chunk_count` above zero, and a search scoped to the source returns a passage from it. In the platform, the source's **Documents** tab lists the same files with the same status.

## Troubleshooting

- **Entries under `failed`**: the `reason` starts with `unsupported_type`, `too_large`, `empty_file` or `read_failed`. Fix the file and upload it again; the others were stored.
- **413**: the request as a whole exceeds the tenant's limit. Upload fewer files per request.
- **400 on upload or ingest**: the source is not a file-upload source. Connector-backed sources sync on their own schedule; `POST /public/v1/sources/<source-id>/sync` starts one on demand.
- **404 or 403 on ingest**: the key's owner did not create the source and may not manage its access.
- **409 on ingest**: a sync is running; it picks up pending documents, so wait for it rather than retrying.
- **502 on upload**: nothing could be stored because the object store was unavailable. Tell your administrator.
- **A document stays `pending`**: no run has picked it up. Check `sync_started` and `sync_note` from the upload, then call ingest.

## Related

- Knowledge
- [Search with citations](/developers/guides/search-with-citations)
- [Browse and curate a source's documents in the help centre](/knowledge/knowledge-bases/documents)
- Authentication

Source: https://docs.katonic.ai/developers/guides/upload-files-and-ingest
