---
title: "Files"
section: "Libraries: Python"
route: /pythonfiles
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Files

Client Files are the most common kind of file in your Nextspace account. You can upload these yourself and tie them to Entity records as attachments. They are also used for markup media, bookmark thumbnails, and branding.

## Uploading

Pass a path and the library handles the rest. Small files go up in a single request, and anything larger is split into parts automatically, so you do not need to know or check the threshold yourself.

```python
import bruce_models as BM

# Upload a file and get its Client File record back.
client_file = BM.ClientFile.upload(bruce, "/path/to/my-file.png")
print(client_file.get("ID"))

# An optional purpose groups the file. Some Nextspace purposes carry extra meaning.
client_file = BM.ClientFile.upload(
    bruce,
    "/path/to/my-file.png",
    purpose="My Purpose"
)
```

Large uploads can take a while, so you can follow their progress. The callback receives a percentage and an `uploaded` flag, which is only true on the final call.

```python
import bruce_models as BM

def on_progress(progress):
    print(f"{progress['percent']}% uploaded={progress['uploaded']}")

client_file = BM.ClientFile.upload(
    bruce,
    "/path/to/large-model.brz",
    on_progress=on_progress
)
```

## Downloading

Every Client File record carries its own absolute `URL`, with the file extension already applied. Use it directly rather than assembling one from the ID and your base url.

```python
import bruce_models as BM
import requests

client_file = BM.ClientFile.get(bruce, "client-file-id")

print(client_file.get("URL"))
print(client_file.get("MIMEType"))
print(client_file.get("OriginalFileName"))
print(client_file.get("OriginalLength"))

# The url needs the same authentication as any other request.
response = requests.get(
    client_file.get("URL"),
    headers={ "Authorization": f"Bearer {your_token}" }
)
with open("downloaded.png", "wb") as handle:
    handle.write(response.content)
```

## Managing

```python
import bruce_models as BM

# Change a file's purpose after the fact.
BM.ClientFile.update_purpose(bruce, "client-file-id", "My New Purpose")

# Delete one or many files.
BM.ClientFile.delete(bruce, [ "client-file-id", "another-client-file-id" ])
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/pythonfiles