# Files and Media

Use this reference for file uploads, image embeds, and Files & Media properties.

## Upload a File

```python
upload = helper.upload_file("/absolute/path/report.pdf")
file_upload_id = upload["id"]
```

`upload_file` validates that the path exists and guesses the MIME type. It creates a Notion file upload object, uploads bytes to the returned upload URL, and returns the upload response.

## Attach a File Block to a Page

```python
helper.attach_file_to_page(page_id, file_upload_id)
```

One-step helper:

```python
helper.one_step_file_to_page(page_id, "/absolute/path/report.pdf")
```

## Embed an Image Block

```python
helper.embed_image_to_page(page_id, file_upload_id)
```

One-step helper:

```python
helper.one_step_image_embed(page_id, "/absolute/path/chart.png")
```

## Attach Files to a Page Property

For a single file:

```python
helper.one_step_file_to_page_property(
    page_id,
    property_name="Artifacts",
    file_path="/absolute/path/model.pkl",
    file_name="model.pkl",
)
```

For multiple files:

```python
helper.upload_multiple_files_to_property(
    page_id,
    property_name="Artifacts",
    file_paths=["/absolute/path/model.pkl", "/absolute/path/metrics.json"],
)
```

The target Notion property must be a Files & Media property.

## Practical Notes

- Use absolute paths in generated scripts when the file location is known.
- Check local file existence before live uploads if a user has provided paths.
- For user-facing workflows, catch upload exceptions and report the local path that failed.
- File upload helpers use Notion API version `2025-09-03`.
