TypeScript / Node

Full TypeScript examples for the HiveClaw API using the native fetch API (Node.js 18+). No external HTTP libraries needed.

API Client

A lightweight, reusable client class:

// hiveclaw.ts
const BASE_URL = 'https://hiveclaw.ai/api/v1/mcp';

class HiveClawClient {
  private apiKey: string;

  constructor(apiKey: string) {
    if (!apiKey.startsWith('hc_')) {
      throw new Error('Invalid API key format. Keys must start with "hc_"');
    }
    this.apiKey = apiKey;
  }

  private async request<T>(
    path: string,
    options: RequestInit = {},
  ): Promise<T> {
    const url = `${BASE_URL}${path}`;
    const res = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    const json = await res.json();

    if (!res.ok) {
      const msg = json.error?.message || res.statusText;
      throw new Error(`HiveClaw API error (${res.status}): ${msg}`);
    }

    return json.data;
  }

  // Projects
  listProjects() {
    return this.request<any[]>('/projects');
  }

  getProject(id: string) {
    return this.request<any>(`/projects/${id}`);
  }

  createProject(name: string, description?: string) {
    return this.request<any>('/projects', {
      method: 'POST',
      body: JSON.stringify({ name, description }),
    });
  }

  // Agents
  listAgents(projectId: string) {
    return this.request<any[]>(`/agents/${projectId}`);
  }

  askAgent(projectId: string, message: string) {
    return this.request<any>(`/agents/${projectId}/ask`, {
      method: 'POST',
      body: JSON.stringify({ message }),
    });
  }

  getMessages(projectId: string, limit = 20) {
    return this.request<any>(`/agents/${projectId}/messages?limit=${limit}`);
  }

  // HivePA
  getPAStatus() {
    return this.request<any>('/pa/status');
  }

  askArchie(message: string) {
    return this.request<any>('/pa/ask', {
      method: 'POST',
      body: JSON.stringify({ message }),
    });
  }

  // Dashboard
  getDashboardSummary() {
    return this.request<any>('/dashboard/summary');
  }

  getUsage(period = '30d') {
    return this.request<any>(`/dashboard/usage?period=${period}`);
  }
}

export default HiveClawClient;

Usage Examples

Initialize the Client

import HiveClawClient from './hiveclaw';

const hc = new HiveClawClient(process.env.HIVECLAW_API_KEY!);

List and Display Projects

async function showProjects() {
  const projects = await hc.listProjects();

  console.log(`Found ${projects.length} projects:\n`);

  for (const p of projects) {
    const bar = '█'.repeat(Math.floor(p.progress / 5))
              + '░'.repeat(20 - Math.floor(p.progress / 5));
    console.log(`  ${p.name} [${bar}] ${p.progress}%`);
    console.log(`    Status: ${p.status} | Phase: ${p.phase}\n`);
  }
}

showProjects();

Create a Project with Intake Flow

async function createProjectWithIntake() {
  // Step 1: Create the project
  const project = await hc.createProject(
    'E-commerce Platform',
    'Full-featured online store with payments',
  );
  console.log('Created project:', project.id);

  // Step 2: Get intake questions
  const intake = await hc.request(`/projects/${project.id}/intake`);
  console.log('Questions:', intake.questions);

  // Step 3: Submit answers
  const answers = intake.questions.map((q: any) => ({
    question_id: q.id,
    answer: 'Sample answer for ' + q.question,
  }));

  await hc.request(`/projects/${project.id}/intake`, {
    method: 'POST',
    body: JSON.stringify({ answers }),
  });

  // Step 4: Submit brief
  const result = await hc.request(`/projects/${project.id}/submit`, {
    method: 'POST',
  });
  console.log('Brief submitted:', result);
}

createProjectWithIntake();

Chat with an Agent

async function chatWithAgent(projectId: string) {
  // Send a message
  const sent = await hc.askAgent(
    projectId,
    'Can you give me a status update on the API endpoints?',
  );
  console.log('Message sent:', sent.message_id);

  // Wait a moment for the agent to respond
  await new Promise((r) => setTimeout(r, 3000));

  // Get the conversation
  const { messages } = await hc.getMessages(projectId, 5);

  for (const msg of messages) {
    const sender = msg.role === 'customer' ? 'You' : msg.agent_role;
    console.log(`[${sender}]: ${msg.content}\n`);
  }
}

chatWithAgent('proj_abc123');

Daily Summary with Archie

async function dailySummary() {
  const response = await hc.askArchie(
    'Give me a summary of all projects that need attention today',
  );

  console.log('Archie says:', response.response);

  if (response.actions?.length > 0) {
    console.log('\nAction items:');
    for (const action of response.actions) {
      console.log(`  - [${action.type}] ${action.project}: ${action.count} items`);
    }
  }
}

dailySummary();

Monitor Dashboard

async function monitorDashboard() {
  const summary = await hc.getDashboardSummary();

  console.log('=== HiveClaw Dashboard ===');
  console.log(`Projects: ${summary.projects.active} active / ${summary.projects.total} total`);
  console.log(`Budget: $${summary.budget_summary.total_remaining} remaining`);

  if (summary.needs_attention.length > 0) {
    console.log('\nNeeds Attention:');
    for (const item of summary.needs_attention) {
      console.log(`  ⚠ ${item.project_name}: ${item.message}`);
    }
  }
}

monitorDashboard();

Error Handling

async function safeApiCall() {
  try {
    const projects = await hc.listProjects();
    console.log('Projects:', projects);
  } catch (error) {
    if (error instanceof Error) {
      if (error.message.includes('401')) {
        console.error('Invalid API key. Check your HIVECLAW_API_KEY.');
      } else if (error.message.includes('403')) {
        console.error('Insufficient permissions. Check your API key scopes.');
      } else if (error.message.includes('429')) {
        console.error('Rate limited. Please wait and try again.');
      } else {
        console.error('API error:', error.message);
      }
    }
  }
}