Getting Started

Quick Start Guide

This guide walks you through authentication, setting up your client, and making your first API call. For an overview of the API, see the Introduction.

Authentication

The Biolevate API uses Bearer token authentication. You authenticate with a Personal Access Token (PAT) generated from a service account. This token must be included in the Authorization header of every request.

Obtaining a PAT

Personal Access Tokens are currently provided by Biolevate upon request. Self-service token management through the Elise admin portal is coming soon.

All API requests must include the token:

Authorization: Bearer <your-pat>

Base URL

All API endpoints are served under the /api/core/ path prefix:

https://<api-domain>/api/core/

Replace <api-domain> with your Elise instance hostname.

Setting Up Your Client

cURL

No setup needed. Pass the token in each request:

curl -X GET "https://<api-domain>/api/core/providers" \
  -H "Authorization: Bearer <your-pat>" \
  -H "Accept: application/json"

Python (httpx)

Using httpx with a persistent client:

import httpx

client = httpx.Client(
    base_url="https://<api-domain>/api/core",
    headers={"Authorization": "Bearer <your-pat>"},
)

tip

Using a persistent httpx.Client enables connection reuse (HTTP keep-alive) and avoids repeating headers on every call.

R

Using httr2 with a reusable base request:

library(httr2)

base_req <- request("https://<api-domain>/api/core") |>
  req_auth_bearer_token("<your-pat>")

All subsequent requests can build on base_req to inherit authentication.

SDK

Using the BiolevateClient async context manager:

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        pass  # client is ready to use here

asyncio.run(main())

See the SDK Overview for installation and error handling details.

Your First Request: Listing Providers

The simplest way to verify your setup is to list the storage providers available on your Elise instance. Providers are configured through the admin UI, so this is a read-only call that returns what has been set up for you.

cURL

curl -s "https://<api-domain>/api/core/providers" \
  -H "Authorization: Bearer <your-pat>" | python3 -m json.tool

Python (httpx)

from pydantic import BaseModel

class Provider(BaseModel):
    name: str
    type: str
    system: bool

class PageResponse(BaseModel):
    data: list[Provider]
    total_pages: int
    total_elements: int
    has_next: bool

response = client.get("/providers")
response.raise_for_status()

page = PageResponse.model_validate(response.json())
for provider in page.data:
    print(f"{provider.name} ({provider.type})")

R

resp <- base_req |>
  req_url_path_append("providers") |>
  req_perform()

providers <- resp_body_json(resp)
for (p in providers$data) {
  cat(sprintf("%s (%s)\n", p$name, p$type))
}

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.providers.list()
        for provider in page.data:
            print(f"{provider.name} ({provider.type_})")

asyncio.run(main())

Understanding the Response

The response is a paginated envelope with the following structure:

{
  "data": [
    {
      "id": { "id": "550e8400-e29b-41d4-a716-446655440000", "entityType": "PROVIDER" },
      "name": "Research Documents",
      "type": "S3",
      "system": false,
      "config": {
        "type": "S3",
        "bucketName": "research-docs",
        "region": "eu-west-1"
      }
    }
  ],
  "totalPages": 1,
  "totalElements": 3,
  "hasNext": false
}

Key fields:

• data: Array of provider objects for the current page
• totalElements: Total number of providers across all pages
• hasNext: Whether more pages are available
• id.id: The UUID you will use to reference this provider in subsequent calls

Secret Redaction

Provider responses redact sensitive configuration fields (connection strings, access keys). Only structural information like bucket names, regions, and site URLs are returned.

Next Steps

Now that you are authenticated and can reach the API:

1. Browse providers to understand your available storage
2. Manage provider items to upload and organize files
3. Index files to trigger document analysis

Related Guides

• Common Patterns: Pagination, error handling, and large file uploads
• API Reference: Complete endpoint documentation