Provider Items

The items resource manages files and folders inside your storage providers. It is available via client.items.

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
0        result = await client.items.list("550e8400-e29b-41d4-a716-446655440000", key="")
        for item in result.items:
            print(f"{item.key} ({item.type_})")

asyncio.run(main())

No automatic indexation

Uploading or creating files via client.items does not trigger document indexation. To index a file, use client.files.create().

The key Concept

All provider item operations identify files and folders using a single key string — the full path within the provider:

Item type	Key format	Example
File	"path/to/file.pdf"	"reports/research-paper.pdf"
Folder	"path/to/folder/" (trailing /)	"reports/2024/"
Root	"" (empty string)	""

Methods

list()

List items in a provider directory. Uses cursor-based pagination.

result = await client.items.list(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/",
)
for item in result.items:
    print(f"{item.key}")

if result.next_cursor:
    next_page = await client.items.list(provider_id, key="reports/", cursor=result.next_cursor)

Parameter	Type	Default	Description
provider_id	str	—	UUID of the provider
key	str	"/"	Directory key to list (must end with / or be empty)

Returns ListItemsResponse

Raises NotFoundError, AuthenticationError, APIError

---

upload()

Upload a file to a provider directory.

with open("report.pdf", "rb") as f:
    item = await client.items.upload(
        provider_id="550e8400-e29b-41d4-a716-446655440000",
        key="reports/",
        file=f,
        file_name="report.pdf",
        mime_type="application/pdf",
    )
print(f"Uploaded: {item.key}")

Parameter	Type	Default	Description
provider_id	str	—	UUID of the provider
key	str	—	Target directory key (must end with /)
file	BinaryIO	—	File-like object opened in binary mode
file_name	str	—	Name for the uploaded file
mime_type	str	"application/octet-stream"	MIME type of the file

Returns ProviderItem

Raises NotFoundError, AuthenticationError, APIError

---

get_upload_url()

Request a presigned upload URL for direct upload to the storage backend, bypassing the API server. Use this for large files.

upload_info = await client.items.get_upload_url(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/large-dataset.csv",
    size=104857600,
    media_type="text/csv",
)

if upload_info.supported and upload_info.url:
    print(f"Upload to: {upload_info.url}")
    print(f"Expires in: {upload_info.expires_in_seconds}s")

Parameter	Type	Default	Description
provider_id	str	—	UUID of the provider
key	str	—	Full file key (must not end with /)
size	int | None	None	File size in bytes
media_type	str | None	None	MIME type of the file

Returns UploadUrlResponse

Raises AuthenticationError, APIError

---

confirm_upload()

After uploading a file to a presigned URL, confirm the upload so the file appears in the provider listing.

item = await client.items.confirm_upload(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/large-dataset.csv",
)
print(f"Confirmed: {item.key}")

Parameter	Type	Description
provider_id	str	UUID of the provider
key	str	Full file key (must not end with /)

Returns ProviderItem

Raises NotFoundError, AuthenticationError, APIError

---

get_download_url()

Get a download URL for a file. Returns a presigned URL for providers that support it, or a proxy URL otherwise.

download = await client.items.get_download_url(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/report.pdf",
    expiration_minutes=60,
)
print(f"Download URL: {download.url}")

Parameter	Type	Default	Description
provider_id	str	—	UUID of the provider
key	str	—	Full file key (must not end with /)
expiration_minutes	int | None	None	URL expiry duration in minutes

Returns DownloadUrlResponse

Raises NotFoundError, AuthenticationError, APIError

---

create_folder()

Create a new folder in a provider.

folder = await client.items.create_folder(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/2024/",
)
print(f"Created folder: {folder.key}")

Parameter	Type	Description
provider_id	str	UUID of the provider
key	str	Full folder key (must end with /)

Returns ProviderItem

Raises AuthenticationError, APIError

---

rename()

Rename a file or folder.

item = await client.items.rename(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/old-name.pdf",
    new_name="new-name.pdf",
)

# Rename a folder
folder = await client.items.rename(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/old-folder/",
    new_name="new-folder",
    item_type="FOLDER",
)

Parameter	Type	Default	Description
provider_id	str	—	UUID of the provider
key	str	—	Full key of the item to rename
new_name	str	—	New name (not a full key, just the name)
item_type	str	"FILE"	"FILE" or "FOLDER"

Returns ProviderItem

Raises NotFoundError, AuthenticationError, APIError

---

delete()

Delete a file or folder.

await client.items.delete(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/old-report.pdf",
)

# Delete a folder
await client.items.delete(
    provider_id="550e8400-e29b-41d4-a716-446655440000",
    key="reports/old-folder/",
)

Parameter	Type	Description
provider_id	str	UUID of the provider
key	str	Full key of the item to delete

Returns None

Raises NotFoundError, AuthenticationError, APIError

Full Example — Presigned Upload Flow

import asyncio
import httpx
from biolevate import BiolevateClient, APIError

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        provider_id = "550e8400-e29b-41d4-a716-446655440000"
        file_key = "data/large-dataset.csv"

        with open("large-dataset.csv", "rb") as f:
            file_bytes = f.read()

        upload_info = await client.items.get_upload_url(
            provider_id=provider_id,
            key=file_key,
            size=len(file_bytes),
            media_type="text/csv",
        )

        if upload_info.supported and upload_info.url:
            async with httpx.AsyncClient() as http:
                response = await http.put(
                    upload_info.url,
                    content=file_bytes,
                    headers={"Content-Type": "text/csv"},
                )
                response.raise_for_status()

            item = await client.items.confirm_upload(
                provider_id=provider_id,
                key=file_key,
            )
            print(f"Uploaded via presigned URL: {item.key}")
        else:
            import io
            item = await client.items.upload(
                provider_id=provider_id,
                key="data/",
                file=io.BytesIO(file_bytes),
                file_name="large-dataset.csv",
                mime_type="text/csv",
            )
            print(f"Uploaded via multipart: {item.key}")

asyncio.run(main())

Next Steps

• Files — index uploaded files to unlock AI-powered analysis
• Managing Provider Items guide — the same operations with cURL, Python (httpx), and R