Skip to content

Getting Started

This guide walks through installing the client, connecting to a Hive instance, and making your first requests.

Prerequisites

  • Python 3.12+
  • Access to a running Hive LMS instance (self-hosted)

Installation

uv add hivelms-client

or with pip

pip install hivelms-client

Create a client

from hivelms_client import HiveClient

client = HiveClient(
    host="hive.example.com",
    username="admin0",
    password="secret",
    port=443,          # default 443
    use_https=True,    # default True
    verify_certs=True, # set False for self-signed certs in dev
)

The client authenticates lazily — it fetches a JWT on the first request and silently refreshes it on 401 responses. You never need to manage tokens yourself.

Make your first requests

Read data

# List all programs
programs = client.course_handler.programs.search()
for p in programs:
    print(p.id, p.name)

# Get a single assignment
assignment = client.assignments_handler.get(42)
print(assignment.assignment_status)

Create a resource

from hivelms_client.models.assignments.assignment import AssignmentInput

assignment = client.assignments_handler.create(
    AssignmentInput(exercise=5, user=12)
)
print(assignment.id)

Partial update

from hivelms_client.models.assignments.assignment import AssignmentPatch, AssignmentStatus

patched = client.assignments_handler.patch(
    assignment.id,
    AssignmentPatch(assignment_status=AssignmentStatus.Done),
)

Delete

client.assignments_handler.delete(assignment.id)

Download a file

file_resp = client.management_handler.users.get_avatar(12)
print(file_resp.filename)   # e.g. "avatar.png"
print(file_resp.mimetype)   # e.g. "image/png"
open("avatar.png", "wb").write(file_resp.content)

Next steps