---
title: "Files"
description: "You upload documents in three steps. Bodo checks type, size, checksum and file signature before a document becomes visible."
lang: en
url: https://developers.bodo-app.com/en/guides/files/
apiVersion: 2026-11-01
---

# Files

You upload documents in three steps. Bodo checks type, size, checksum and file signature before a document becomes visible.

## Upload in three steps

### 1. Create an upload session

`POST /v1/uploads` with name, type, size and SHA-256. The answer names method, address and headers for the file; the target is valid for 15 minutes, the session for 24 hours.

### 2. Send the raw bytes

Exactly with method, address and headers from the answer, without `Authorization` and without multipart. Ignore the answer of the store.

### 3. Create the document

`POST /v1/documents` with the `uploadId` answers 202 with an operation. Once the check passes, the document is in the operation and the event `document.created` goes out.

## With the SDK

The SDK walks all three steps and waits for the operation.

TypeScript · SDK:

```typescript
// Portal D3 · Files and upload — session, raw bytes, document; the SDK follows method, URL and
// headers of the session (no Authorization to the storage) and waits for the operation.
// Run: BODO_API_KEY=bodo_uk_test_… bun examples/upload-document.ts ./vertrag.pdf
import { readFile } from "node:fs/promises";
import { basename } from "node:path";
import { Bodo } from "@bodo/api";

const bodo = new Bodo({ apiKey: process.env.BODO_API_KEY, preview: true });
const path = process.argv[2] ?? "vertrag.pdf";

const operation = await bodo.uploads.uploadDocument({
  bytes: await readFile(path),
  fileName: basename(path),
  contentType: "application/pdf",
});
const done = await bodo.operations.wait(operation.id); // throws BodoApiError when the check fails
console.log(done.status, done.result);
```

Python · SDK:

```python
# Session, raw bytes, document; the SDK follows method, URL and
# headers of the session (no Authorization to the storage) and waits for the operation.
# Run: BODO_API_KEY=bodo_uk_test_… python examples/upload_document.py ./vertrag.pdf
import os
import pathlib
import sys

from bodo_api import Bodo

path = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "vertrag.pdf")
with Bodo(api_key=os.environ["BODO_API_KEY"], preview=True) as bodo:
    operation = bodo.uploads.upload_document(
        path.read_bytes(),
        file_name=path.name,
        content_type="application/pdf",
    )
    done = bodo.operations.wait(operation.id)  # raises BodoApiError when the check fails
    print(done.status, done.result)
```

## What gets rejected

| Case | Answer |
| --- | --- |
| Type not allowed or file larger than 50 MB | [422 VALIDATION_FAILED](/en/problems/VALIDATION_FAILED/) with a field error, already when creating the session |
| Document created before the file is complete | [409 UPLOAD_INCOMPLETE](/en/problems/UPLOAD_INCOMPLETE/) |
| Size or SHA-256 do not match the session | [422 UPLOAD_CHECKSUM_MISMATCH](/en/problems/UPLOAD_CHECKSUM_MISMATCH/) |
| File signature does not match the type | [422 UPLOAD_REJECTED](/en/problems/UPLOAD_REJECTED/), no document is created |

## Download

`GET /v1/documents/{id}/content` answers 302 with a signed address valid for 5 minutes. Follow the redirect without `Authorization`; do not pass the address on.