Skip to main content

Collections

The collections resource manages logical groups of EliseFiles. It is available via client.collections.

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection = await client.collections.create(
            name="Q1 Research Papers",
            description="Research papers reviewed during Q1",
        )
        print(f"Created: {collection.id.id}")

asyncio.run(main())

Methods

`list()`

List collections accessible to your account.

page = await client.collections.list(
    page=0,
    page_size=20,
    query="research",
    sort_by="name",
    sort_order="asc",
)
for coll in page.data:
    print(f"{coll.name} ({coll.files_count} files)")

Parameter	Type	Default	Description
`page`	`int`	`0`	Page number (0-based)
`page_size`	`int`	`20`	Number of collections per page
`sort_by`	`str \| None`	`None`	Field to sort by
`sort_order`	`str`	`"asc"`	Sort direction — `"asc"` or `"desc"`
`query`	`str \| None`	`None`	Text filter on collection names

Returns CollectionPage

Raises AuthenticationError, APIError

`create()`

Create a new collection.

collection = await client.collections.create(
    name="Q1 Research Papers",
    description="Research papers reviewed during Q1",
)
print(f"Created: {collection.id.id}")

Parameter	Type	Default	Description
`name`	`str`	—	Collection name
`description`	`str \| None`	`None`	Optional description

Returns Collection

Raises AuthenticationError, APIError

`get()`

Retrieve a single collection by its UUID.

collection = await client.collections.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(f"{collection.name}: {collection.files_count} files")

Parameter	Type	Description
`collection_id`	`str`	UUID of the collection

Returns Collection

Raises NotFoundError, AuthenticationError, APIError

`update()`

Update a collection's name or description.

collection = await client.collections.update(
    collection_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    name="Q1 Research — Final",
    description="Finalised Q1 research set",
)

Parameter	Type	Default	Description
`collection_id`	`str`	—	UUID of the collection
`name`	`str \| None`	`None`	New name (omit to leave unchanged)
`description`	`str \| None`	`None`	New description (omit to leave unchanged)

Returns Collection

Raises NotFoundError, AuthenticationError, APIError

`delete()`

Delete a collection. Only the owner can delete a collection.

await client.collections.delete("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

Parameter	Type	Description
`collection_id`	`str`	UUID of the collection

Returns None

Raises NotFoundError, AuthenticationError, APIError

`list_files()`

List all EliseFiles in a collection with pagination.

page = await client.collections.list_files(
    collection_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    page=0,
    page_size=20,
)
for file in page.data:
    print(f"{file.name} (indexed: {file.indexed})")

Parameter	Type	Default	Description
`collection_id`	`str`	—	UUID of the collection
`page`	`int`	`0`	Page number (0-based)
`page_size`	`int`	`20`	Number of files per page

Returns FilePage

Raises NotFoundError, AuthenticationError, APIError

`add_file()`

Add an EliseFile to a collection.

await client.collections.add_file(
    collection_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    file_id="b2c3d4e5-f6a7-8901-bcde-f12345678901",
)

Parameter	Type	Description
`collection_id`	`str`	UUID of the collection
`file_id`	`str`	UUID of the EliseFile to add

Returns File

Raises NotFoundError, AuthenticationError, APIError

`remove_file()`

Remove an EliseFile from a collection. The file itself is not deleted.

await client.collections.remove_file(
    collection_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    file_id="b2c3d4e5-f6a7-8901-bcde-f12345678901",
)

Parameter	Type	Description
`collection_id`	`str`	UUID of the collection
`file_id`	`str`	UUID of the EliseFile to remove

Returns None

Raises NotFoundError, AuthenticationError, APIError

Full Example

import asyncio
from biolevate import BiolevateClient, NotFoundError

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection = await client.collections.create(
            name="Q1 Research Papers",
            description="Research papers reviewed during Q1",
        )
        collection_id = collection.id.id
        print(f"Created collection: {collection_id}")

        file_ids = [
            "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        ]
        for file_id in file_ids:
            await client.collections.add_file(collection_id, file_id)
            print(f"Added file: {file_id}")

        page = await client.collections.list_files(collection_id)
        print(f"Collection now has {page.total_elements} files")

        await client.collections.update(
            collection_id,
            name="Q1 Research Papers — Final",
        )
        print("Collection updated")

asyncio.run(main())

Next Steps

Question Answering — run AI jobs on all files in a collection using collection_ids
Extraction — extract structured metadata from files in a collection
Collections guide — the same operations with cURL, Python (httpx), and R

Methods
Full Example
Next Steps