Collections

Organizing Files

Collections are logical groups of EliseFiles. Use them to organize indexed documents into projects, workspaces, or any grouping that fits your workflow. A file can belong to multiple collections.

Creating a Collection

Create a new collection with a name and an optional description and icon.

cURL

curl -X POST "https://<api-domain>/api/core/collections" \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Research Papers",
    "description": "Research papers collected during Q1 review",
    "icon": "folder"
  }'

Python (httpx)

from pydantic import BaseModel, Field

class CollectionId(BaseModel):
    id: str
    entity_type: str = Field(alias="entityType")

class CollectionInfo(BaseModel):
    id: CollectionId
    name: str
    description: str | None = None
    icon: str | None = None
    files_count: int = Field(default=0, alias="filesCount")
    owner_email: str | None = Field(default=None, alias="ownerEmail")

response = client.post(
    "/collections",
    json={
        "name": "Q1 Research Papers",
        "description": "Research papers collected during Q1 review",
        "icon": "folder",
    },
)
response.raise_for_status()

collection = CollectionInfo.model_validate(response.json())
print(f"Created collection: {collection.id.id}")
print(f"  Name: {collection.name}")

R

resp <- base_req |>
  req_url_path_append("collections") |>
  req_body_json(list(
    name = "Q1 Research Papers",
    description = "Research papers collected during Q1 review",
    icon = "folder"
  )) |>
  req_perform()

collection <- resp_body_json(resp)
cat(sprintf("Created collection: %s\n", collection$id$id))
cat(sprintf("  Name: %s\n", collection$name))

SDK

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 collected during Q1 review",
        )
        print(f"Created collection: {collection.id.id}")
        print(f"  Name: {collection.name}")

asyncio.run(main())

Listing Collections

Retrieve a paginated list of collections accessible to your account.

cURL

curl -s "https://<api-domain>/api/core/collections?page=0&pageSize=20" \
  -H "Authorization: Bearer <your-pat>"

Python (httpx)

class CollectionPage(BaseModel):
    data: list[CollectionInfo]
    total_pages: int = Field(alias="totalPages")
    total_elements: int = Field(alias="totalElements")
    has_next: bool = Field(alias="hasNext")

response = client.get("/collections", params={"page": 0, "pageSize": 20})
response.raise_for_status()

page = CollectionPage.model_validate(response.json())
for coll in page.data:
    print(f"{coll.id.id}: {coll.name} ({coll.files_count} files)")

R

resp <- base_req |>
  req_url_path_append("collections") |>
  req_url_query(page = 0, pageSize = 20) |>
  req_perform()

page <- resp_body_json(resp)
for (coll in page$data) {
  cat(sprintf("%s: %s (%d files)\n", coll$id$id, coll$name, coll$filesCount))
}

SDK

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        page = await client.collections.list(page=0, page_size=20)
        for coll in page.data:
            print(f"{coll.id.id}: {coll.name} ({coll.files_count} files)")

asyncio.run(main())

Query Parameters

Parameter	Type	Default	Description
page	integer	0	Page number (0-based)
pageSize	integer	20	Number of items per page
sortBy	string	--	Field to sort by
sortOrder	string	asc	Sort direction (asc or desc)
q	string	--	Text search filter on collection names

Getting a Collection

Retrieve a single collection by its UUID.

cURL

curl -s "https://<api-domain>/api/core/collections/${COLLECTION_ID}" \
  -H "Authorization: Bearer <your-pat>"

Python (httpx)

collection_id = collection.id.id

response = client.get(f"/collections/{collection_id}")
response.raise_for_status()

coll = CollectionInfo.model_validate(response.json())
print(f"{coll.name}: {coll.files_count} files")

R

collection_id <- collection$id$id

resp <- base_req |>
  req_url_path_append("collections", collection_id) |>
  req_perform()

coll <- resp_body_json(resp)
cat(sprintf("%s: %d files\n", coll$name, coll$filesCount))

SDK

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        coll = await client.collections.get(collection_id)
        print(f"{coll.name}: {coll.files_count} files")

asyncio.run(main())

Updating a Collection

Partially update a collection. Only the fields you provide will be modified.

cURL

curl -X PATCH "https://<api-domain>/api/core/collections/${COLLECTION_ID}" \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 2026 Research Papers", "description": "Updated description"}'

Python (httpx)

response = client.patch(
    f"/collections/{collection_id}",
    json={"name": "Q1 2026 Research Papers", "description": "Updated description"},
)
response.raise_for_status()

updated = CollectionInfo.model_validate(response.json())
print(f"Updated: {updated.name}")

R

resp <- base_req |>
  req_url_path_append("collections", collection_id) |>
  req_method("PATCH") |>
  req_body_json(list(name = "Q1 2026 Research Papers", description = "Updated description")) |>
  req_perform()

updated <- resp_body_json(resp)
cat(sprintf("Updated: %s\n", updated$name))

SDK

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        updated = await client.collections.update(
            collection_id,
            name="Q1 2026 Research Papers",
            description="Updated description",
        )
        print(f"Updated: {updated.name}")

asyncio.run(main())

Deleting a Collection

Delete a collection. Only the collection owner can perform this operation. Deleting a collection does not delete the files it contains.

cURL

curl -X DELETE "https://<api-domain>/api/core/collections/${COLLECTION_ID}" \
  -H "Authorization: Bearer <your-pat>"

Python (httpx)

response = client.delete(f"/collections/{collection_id}")
response.raise_for_status()
print("Collection deleted (204 No Content)")

R

base_req |>
  req_url_path_append("collections", collection_id) |>
  req_method("DELETE") |>
  req_perform()

cat("Collection deleted (204 No Content)\n")

SDK

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        await client.collections.delete(collection_id)
        print("Collection deleted")

asyncio.run(main())

Owner Only

Only the owner of a collection can delete it. Attempting to delete a collection you do not own returns a 403 Forbidden error.

Adding Files to a Collection

Associate an existing EliseFile with a collection. The file must already exist (created via the Files endpoint).

cURL

curl -X POST "https://<api-domain>/api/core/collections/${COLLECTION_ID}/files" \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Python (httpx)

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = client.post(
    f"/collections/{collection_id}/files",
    json={"fileId": file_id},
)
response.raise_for_status()

added_file = EliseFileInfo.model_validate(response.json())
print(f"Added {added_file.name} to collection")

R

file_id <- "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

resp <- base_req |>
  req_url_path_append("collections", collection_id, "files") |>
  req_body_json(list(fileId = file_id)) |>
  req_perform()

added_file <- resp_body_json(resp)
cat(sprintf("Added %s to collection\n", added_file$name))

SDK

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        file_id = "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        file = await client.collections.add_file(collection_id, file_id)
        print(f"Added {file.name} to collection")

asyncio.run(main())

Listing Files in a Collection

Retrieve the files belonging to a collection with pagination and optional search filtering.

Query Parameters

Parameter	Type	Default	Description
page	integer	0	Page number (0-based)
pageSize	integer	20	Number of items per page
sortBy	string	--	Field to sort by
sortOrder	string	asc	Sort direction (asc or desc)
q	string	--	Text search filter on file names

cURL

curl -s "https://<api-domain>/api/core/collections/${COLLECTION_ID}/files?page=0&pageSize=20" \
  -H "Authorization: Bearer <your-pat>"

Python (httpx)

class FilePage(BaseModel):
    data: list[EliseFileInfo]
    total_pages: int = Field(alias="totalPages")
    total_elements: int = Field(alias="totalElements")
    has_next: bool = Field(alias="hasNext")

response = client.get(
    f"/collections/{collection_id}/files",
    params={"page": 0, "pageSize": 20},
)
response.raise_for_status()

file_page = FilePage.model_validate(response.json())
for f in file_page.data:
    status = f.last_indexation_infos.status if f.last_indexation_infos else "N/A"
    print(f"{f.name} - indexed: {f.indexed}, status: {status}")

R

resp <- base_req |>
  req_url_path_append("collections", collection_id, "files") |>
  req_url_query(page = 0, pageSize = 20) |>
  req_perform()

file_page <- resp_body_json(resp)
for (f in file_page$data) {
  status <- if (!is.null(f$lastIndexationInfos)) f$lastIndexationInfos$status else "N/A"
  cat(sprintf("%s - indexed: %s, status: %s\n", f$name, f$indexed, status))
}

SDK

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        file_page = await client.collections.list_files(collection_id, page=0, page_size=20)
        for f in file_page.data:
            print(f"{f.name} - indexed: {f.indexed}")

asyncio.run(main())

Removing a File from a Collection

Remove the association between a file and a collection. The EliseFile itself is not deleted.

cURL

curl -X DELETE "https://<api-domain>/api/core/collections/${COLLECTION_ID}/files/${FILE_ID}" \
  -H "Authorization: Bearer <your-pat>"

Python (httpx)

response = client.delete(f"/collections/{collection_id}/files/{file_id}")
response.raise_for_status()
print("File removed from collection (204 No Content)")

R

base_req |>
  req_url_path_append("collections", collection_id, "files", file_id) |>
  req_method("DELETE") |>
  req_perform()

cat("File removed from collection (204 No Content)\n")

SDK

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        collection_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        file_id = "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        await client.collections.remove_file(collection_id, file_id)
        print("File removed from collection")

asyncio.run(main())

Next Steps

• Common Patterns for pagination, error handling, and advanced workflows
• API Reference for complete endpoint documentation

Bulk Operations

To add multiple files to a collection, call the add file endpoint for each file. There is currently no bulk endpoint, but you can parallelize requests for efficiency.