# Uploading Files through the API

The upload API sends a file in server-sized parts, then queues it for processing.
Finishing the transfer and completing processing are separate steps.

![Upload and Process a File: the four steps and their completion checks.](/screenshots/current/file-upload.svg)

## Before you start

You need Python 3.10 or later, an [API key](/quickstart/), and a writable Knowledge
folder. Open that folder in Redbelt: its URL has the form
**/knowledge/FOLDER_ID**. Use that UUID as **REDBELT_FOLDER_ID**.

The API key's identity must have write access to the folder. A service account
does not automatically inherit the creator's private folders.
Choose a supported file type and a nonempty file no larger than **512 MiB**
(536,870,912 bytes).

## Upload and confirm processing

Set **REDBELT_API_KEY** as described in the quickstart and set your folder ID:

```bash
export REDBELT_FOLDER_ID="YOUR_FOLDER_UUID"
```

Save this as **upload_file.py**:

```python
"""Upload a file in server-sized parts and wait for its processing result."""

import json
import os
import sys
import time
from pathlib import Path
from urllib.request import Request, urlopen


def upload_file(api_url, api_key, folder_id, file_path, *, timeout=300):
    path = Path(file_path)
    size = path.stat().st_size
    if not 0 < size <= 512 * 1024 * 1024:
        raise ValueError("Choose a nonempty file no larger than 512 MiB.")

    def call(method, route, *, payload=None, body=None):
        headers = {"Authorization": f"Bearer {api_key}"}
        if payload is not None:
            body = json.dumps(payload).encode()
            headers["Content-Type"] = "application/json"
        elif body is not None:
            headers["Content-Type"] = "application/octet-stream"
        request = Request(
            api_url.rstrip("/") + route,
            data=body,
            headers=headers,
            method=method,
        )
        with urlopen(request, timeout=60) as response:
            return json.load(response)

    started = call(
        "POST",
        "/files/uploads/start",
        payload={
            "folder_id": folder_id,
            "file_name": path.name,
            "size": size,
        },
    )
    upload_id = started["upload_id"]
    with path.open("rb") as source:
        for part_number in range(1, started["num_parts"] + 1):
            chunk = source.read(started["part_size"])
            if not chunk:
                raise ValueError(
                    "The file changed or ended before all parts were read."
                )
            received = call(
                "PUT",
                f"/files/uploads/{upload_id}/part/{part_number}",
                body=chunk,
            )
            if received["received_bytes"] != len(chunk):
                raise RuntimeError("The server did not acknowledge the complete part.")
        if source.read(1):
            raise ValueError("The file grew after the upload session started.")

    call("POST", f"/files/uploads/{upload_id}/finish")
    deadline = time.monotonic() + timeout
    while True:
        session = call("GET", f"/files/uploads/{upload_id}")
        if session["status"] == "completed":
            return upload_id
        if session["status"] in {"error", "aborted"}:
            raise RuntimeError(
                f"Upload {upload_id} ended with status {session['status']}."
            )
        if time.monotonic() >= deadline:
            raise TimeoutError(f"Processing is still pending for upload {upload_id}.")
        time.sleep(2)


if __name__ == "__main__":
    result = upload_file(
        os.environ.get("REDBELT_API_URL", "https://redbelt.ai/api"),
        os.environ["REDBELT_API_KEY"],
        os.environ["REDBELT_FOLDER_ID"],
        sys.argv[1],
    )
    print("Completed upload:", result)

```

Run it with a small document first:

```bash
python3 upload_file.py document.pdf
```

This script reads the file without loading it all into memory. It uses the
server's part size and number of parts, checks each acknowledgment, finishes the
upload, and polls for a terminal processing status. It checks a five-minute
processing deadline between status requests; a timeout does not cancel the
server's work.

## Understand each step

| Step             | Endpoint                                              | Successful result                                                                    |
| ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Start            | **POST /api/files/uploads/start**                     | **201** with **upload_id**, **part_size**, **num_parts**, and **file_type_id**.      |
| Send a part      | **PUT /api/files/uploads/UPLOAD_ID/part/PART_NUMBER** | Acknowledgment with **part_number** and **received_bytes**. Part numbers start at 1. |
| Finish           | **POST /api/files/uploads/UPLOAD_ID/finish**          | **202**, usually with status **queued**.                                             |
| Check processing | **GET /api/files/uploads/UPLOAD_ID**                  | Upload session including **status** and part counts.                                 |

These responses are JSON objects directly. Binary parts use
**application/octet-stream**; the start request uses **application/json**.

Session statuses include **uploading**, **queued**, **processing**, **completed**,
**error**, and **aborted**. Treat **completed** as successful processing.
Use **GET /api/files/UPLOAD_ID** for the file's metadata.

## Check the result in Redbelt

Open the destination Knowledge folder. Find the file, open it, and confirm its
content is available. You can then reference its **upload_id** in an
[agent thread](/chat_agents/).

## Interrupted or failed uploads

* Inspect **GET /api/files/uploads/UPLOAD_ID** before deciding how to recover an
  interrupted transfer.
* To discard an incomplete upload, use **DELETE /api/files/uploads/UPLOAD_ID**.
  Successful deletion returns **204** with no JSON body. It is allowed for
  uploading or errored sessions; it cannot cancel every later processing state.
* For a processing error, inspect the file's status in Knowledge and confirm the
  format is supported.
* For access errors, check the folder's permissions for the API key identity.
* Do not blindly repeat the start request: that can create another upload.

For the complete schemas, use the [API reference](/api/reference.html).
For the browser interface, see [add content to Knowledge](/knowledge/upload/).
