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.