API

API Reference

There are two API surfaces in the Hive ecosystem — the hub, which manages the fleet, and each hive's own spoke API.

Hub API

hive.kubestellar.io

Manages hive registry, users, access control, hosted hive provisioning, leaderboard. Documented below.

Spoke API

each hive instance

The actual hive dashboard — agents, governor, config, contributors, beads, tokens. Available at each hive's URL (e.g. 192.168.4.85:3001 or hosted-*.hive.kubestellar.io).

Connect

Full Reference

Base URL

https://hive.kubestellar.io

Authentication

The Hub uses GitHub OAuth with a session cookie. Public endpoints (registry, leaderboard, stats) require no auth. Dashboard and management endpoints require login.

Step 1: Login via browser

Visit /login — you'll be redirected to GitHub to authorize. After approval, a hive_hub_user cookie is set on .hive.kubestellar.io.

Step 2: Use the cookie in API calls

# Public — no auth needed
curl https://hive.kubestellar.io/api/registry
curl https://hive.kubestellar.io/api/hub/leaderboard
curl https://hive.kubestellar.io/api/hub/stats

# Authenticated — pass the cookie
curl -b "hive_hub_user=YOUR_USERNAME" \
  https://hive.kubestellar.io/api/saas/my-hives

Quick Examples

List all public hives

curl -s https://hive.kubestellar.io/api/registry | jq '.hives[] | {id, name, acmmLevel, governorMode, online}'

Get leaderboard

curl -s https://hive.kubestellar.io/api/hub/leaderboard | jq '.leaderboard[] | {github_username, tasks_completed, current_task}'

Create a hosted hive (requires login + quota)

curl -X POST -b "hive_hub_user=YOUR_USERNAME" \
  -H "Content-Type: application/json" \
  -d '{"org":"my-org","repos":"my-repo","acmm_level":3,"auth_method":"pat","github_token":"ghp_..."}' \
  https://hive.kubestellar.io/api/saas/hives

Grant access to a hosted hive

curl -X POST -b "hive_hub_user=YOUR_USERNAME" \
  -H "Content-Type: application/json" \
  -d '{"username":"collaborator","role":"read-write"}' \
  https://hive.kubestellar.io/api/saas/hives/HIVE_ID/access

Spoke Integration

Hive spoke instances push status to the hub via heartbeats. Configure your hive to register:

hive.yaml

hub:
  enabled: true
  url: https://hive.kubestellar.io
  is_public: true
  dashboard_url: http://YOUR_IP:3001
  snapshot_url: https://your-snapshot-url

Or set the environment variable: HIVE_HUB_URL=https://hive.kubestellar.io

Authentication is required. POST /api/heartbeat rejects any beat without a valid Authorization: Bearer <HIVE_HUB_SECRET> header when the hub has a secret configured, so the settings above only take effect once the hub operator has issued your spoke a HIVE_HUB_SECRET. A spoke configured without one logs hub heartbeat rejected status=401 every beat and never appears in the registry.

Rate Limits

The hub does not enforce API rate limits. GitHub API rate limits apply to spoke heartbeats (GitHub App: 5000/hr per installation, PAT: 5000/hr per user). Spokes push heartbeats every 5 minutes and task updates every 30 seconds.