Python

Python examples using the requests library. Install it with pip install requests if you don't have it already.

API Client

A reusable client class:

# hiveclaw.py
import os
import requests

BASE_URL = "https://hiveclaw.ai/api/v1/mcp"


class HiveClawClient:
    def __init__(self, api_key: str | None = None):
        self.api_key = api_key or os.environ.get("HIVECLAW_API_KEY", "")
        if not self.api_key.startswith("hc_"):
            raise ValueError('Invalid API key format. Keys must start with "hc_"')
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        })

    def _request(self, method: str, path: str, **kwargs) -> dict:
        url = f"{BASE_URL}{path}"
        resp = self.session.request(method, url, **kwargs)
        data = resp.json()
        if not resp.ok:
            msg = data.get("error", {}).get("message", resp.reason)
            raise Exception(f"HiveClaw API error ({resp.status_code}): {msg}")
        return data.get("data")

    # Projects
    def list_projects(self):
        return self._request("GET", "/projects")

    def get_project(self, project_id: str):
        return self._request("GET", f"/projects/{project_id}")

    def create_project(self, name: str, description: str = ""):
        return self._request("POST", "/projects", json={
            "name": name,
            "description": description,
        })

    def get_intake_questions(self, project_id: str):
        return self._request("GET", f"/projects/{project_id}/intake")

    def submit_intake(self, project_id: str, answers: list):
        return self._request("POST", f"/projects/{project_id}/intake", json={
            "answers": answers,
        })

    def submit_brief(self, project_id: str):
        return self._request("POST", f"/projects/{project_id}/submit")

    def get_estimate(self, project_id: str):
        return self._request("GET", f"/projects/{project_id}/estimate")

    # Agents
    def list_agents(self, project_id: str):
        return self._request("GET", f"/agents/{project_id}")

    def ask_agent(self, project_id: str, message: str):
        return self._request("POST", f"/agents/{project_id}/ask", json={"message": message})

    def get_messages(self, project_id: str, limit: int = 20):
        return self._request("GET", f"/agents/{project_id}/messages?limit={limit}")

    # HivePA
    def pa_status(self):
        return self._request("GET", "/pa/status")

    def ask_archie(self, message: str):
        return self._request("POST", "/pa/ask", json={"message": message})

    def pa_task(self, task: str, project_id: str = None):
        body = {"task": task}
        if project_id:
            body["project_id"] = project_id
        return self._request("POST", "/pa/task", json=body)

    # Vault
    def list_credentials(self, project_id: str = None):
        path = "/vault/credentials"
        if project_id:
            path += f"?project_id={project_id}"
        return self._request("GET", path)

    def list_credential_requests(self, status: str = None):
        path = "/vault/requests"
        if status:
            path += f"?status={status}"
        return self._request("GET", path)

    # Dashboard
    def dashboard_summary(self):
        return self._request("GET", "/dashboard/summary")

    def usage(self, period: str = "30d"):
        return self._request("GET", f"/dashboard/usage?period={period}")

Usage Examples

Initialize the Client

from hiveclaw import HiveClawClient

# Uses HIVECLAW_API_KEY environment variable
hc = HiveClawClient()

# Or pass the key directly
hc = HiveClawClient("hc_your_key_here")

List Projects

projects = hc.list_projects()

for p in projects:
    progress = int(p["progress"] / 5)
    bar = "█" * progress + "░" * (20 - progress)
    print(f"  {p['name']} [{bar}] {p['progress']}%")
    print(f"    Status: {p['status']} | Phase: {p['phase']}\n")

Create a Project

# Create
project = hc.create_project(
    name="Mobile App",
    description="Cross-platform mobile app with React Native",
)
print(f"Created: {project['id']}")

# Answer intake questions
intake = hc.get_intake_questions(project["id"])
answers = [
    {"question_id": q["id"], "answer": "My answer"}
    for q in intake["questions"]
]
hc.submit_intake(project["id"], answers)

# Submit the brief
result = hc.submit_brief(project["id"])
print(f"Status: {result['status']}")

Talk to Agents

import time

project_id = "proj_abc123"

# Send a message
result = hc.ask_agent(
    project_id,
    "How is the database schema design going?",
)
print(f"Sent: {result['message_id']}")

# Wait for response
time.sleep(3)

# Read conversation
data = hc.get_messages(project_id, limit=5)
for msg in data["messages"]:
    sender = "You" if msg["role"] == "customer" else msg.get("agent_role", "Agent")
    print(f"[{sender}]: {msg['content']}\n")

Daily Summary Script

def daily_summary():
    """Print a daily summary of all HiveClaw activity."""

    # Get PA summary
    pa = hc.pa_status()
    print(f"Active projects: {pa['active_projects']}")
    print(f"Pending approvals: {pa['pending_approvals']}")
    print(f"Unread messages: {pa['unread_messages']}")

    # Ask Archie for priorities
    response = hc.ask_archie("What should I focus on today?")
    print(f"\nArchie: {response['response']}")

    # Get dashboard data
    summary = hc.dashboard_summary()
    budget = summary["budget_summary"]
    print(f"\nBudget: {budget['total_remaining']:,{"}"} remaining")

    # Show items needing attention
    if summary["needs_attention"]:
        print("\nNeeds attention:")
        for item in summary["needs_attention"]:
            print(f"  ⚠ {item['project_name']}: {item['message']}")

daily_summary()

Monitor Credential Requests

def check_credential_requests():
    """Check for pending credential requests from agents."""
    requests = hc.list_credential_requests(status="pending")

    if not requests:
        print("No pending credential requests.")
        return

    print(f"Found {len(requests)} pending request(s):\n")
    for req in requests:
        print(f"  Project: {req['project_name']}")
        print(f"  Credential: {req['credential_name']} ({req['credential_type']})")
        print(f"  Reason: {req['reason']}")
        print(f"  Requested by: {req['requested_by']}")
        print()

check_credential_requests()

Error Handling

def safe_api_call():
    try:
        projects = hc.list_projects()
        print(f"Found {len(projects)} projects")
    except Exception as e:
        error_msg = str(e)
        if "401" in error_msg:
            print("Invalid API key. Check HIVECLAW_API_KEY.")
        elif "403" in error_msg:
            print("Insufficient permissions. Check API key scopes.")
        elif "429" in error_msg:
            print("Rate limited. Wait and retry.")
        else:
            print(f"API error: {error_msg}")

Requirements

# requirements.txt
requests>=2.28.0

The client uses only the requests library. For async support, you can adapt the client to use httpx with AsyncClient.