Skip to main content

API Overview

The HornetHive API provides programmatic access to all crew functionality, allowing you to deploy AI crews, monitor outcomes, and integrate with your existing systems.

Base URL​

All API requests should be made to:

https://api.hornethive.ai/v1

Authentication​

API requests require an API key passed in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.hornethive.ai/v1/crews

Getting Your API Key​

  1. Log in to app.hornethive.ai
  2. Go to Settings → API Keys
  3. Click Generate New Key
  4. Copy and securely store your key

⚠️ Security Note: Never expose API keys in client-side code or public repositories.

Core Endpoints​

Crews​

List Available Crews​

GET /v1/crews

Response:

{
  "crews": [
    {
      "id": "hivewriter",
      "name": "HiveWriter",
      "description": "Content creation and publishing automation",
      "agents": ["ContentAgent", "EditorAgent", "PublisherAgent"],
      "status": "available"
    }
  ]
}

Deploy a Crew​

POST /v1/crews/{crew_id}/run

Request Body:

{
  "brief": "Write a blog post about AI automation for small businesses",
  "context": "Target audience: 10-50 person companies looking to scale",
  "requirements": {
    "tone": "professional but approachable",
    "length": "800-1200 words",
    "format": "markdown"
  },
  "integrations": {
    "publish_to_linkedin": true,
    "save_to_drive": true
  }
}

Response:

{
  "outcome_id": "out_1234567890",
  "status": "processing",
  "estimated_completion": "2024-01-15T10:35:00Z",
  "crew_deployed": "hivewriter"
}

Outcomes​

Get Outcome Status​

GET /v1/outcomes/{outcome_id}

Response:

{
  "id": "out_1234567890",
  "status": "completed",
  "crew": "hivewriter",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:33:24Z",
  "result": {
    "content": "# AI Automation for Small Businesses...",
    "metadata": {
      "word_count": 1024,
      "reading_time": "4 minutes",
      "sentiment": "positive"
    }
  },
  "revisions_available": 1
}

Request Revision​

POST /v1/outcomes/{outcome_id}/revise

Request Body:

{
  "feedback": "Make the tone more casual and add more specific examples",
  "requirements": {
    "tone": "casual",
    "examples": "at least 3 real-world examples"
  }
}

List Your Outcomes​

GET /v1/outcomes?limit=20&status=completed

Query Parameters:

  • limit: Number of results (default: 10, max: 100)
  • status: Filter by status (processing, completed, failed)
  • crew: Filter by crew type
  • created_after: ISO 8601 timestamp

Integrations​

List Available Integrations​

GET /v1/integrations

Configure Integration​

POST /v1/integrations/{integration_id}/configure

Request Body (Slack example):

{
  "settings": {
    "channel": "#general",
    "notify_on_completion": true,
    "import_context": true
  }
}

Webhooks​

Configure webhooks to receive real-time notifications when outcomes are completed.

Setting Up Webhooks​

POST /v1/webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/hornethive",
  "events": ["outcome.completed", "outcome.failed"],
  "secret": "your_webhook_secret"
}

Webhook Payload​

{
  "event": "outcome.completed",
  "timestamp": "2024-01-15T10:33:24Z",
  "data": {
    "outcome_id": "out_1234567890",
    "crew": "hivewriter",
    "status": "completed",
    "result_url": "https://api.hornethive.ai/v1/outcomes/out_1234567890"
  }
}

Verifying Webhooks​

Verify webhook authenticity using HMAC-SHA256:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

SDKs and Libraries​

Node.js​

npm install @hornethive/api
import { HornetHive } from '@hornethive/api';

const client = new HornetHive('your_api_key');

const outcome = await client.crews.deploy('hivewriter', {
  brief: 'Write a blog post about AI automation',
  context: 'Target audience: small business owners'
});

console.log(`Outcome ID: ${outcome.id}`);

Python​

pip install hornethive
from hornethive import HornetHive

client = HornetHive('your_api_key')

outcome = client.crews.deploy('hivewriter', {
    'brief': 'Write a blog post about AI automation',
    'context': 'Target audience: small business owners'
})

print(f"Outcome ID: {outcome.id}")

cURL Examples​

Deploy HiveWriter for Blog Post​

curl -X POST "https://api.hornethive.ai/v1/crews/hivewriter/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Write a technical blog post about microservices",
    "context": "Developer audience, 1000+ words",
    "requirements": {
      "tone": "technical but accessible",
      "include_code_examples": true
    }
  }'

Deploy HivePilot for PRD​

curl -X POST "https://api.hornethive.ai/v1/crews/hivepilot/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Create PRD for user notification system",
    "context": "SaaS platform with 10k+ users",
    "requirements": {
      "format": "standard_prd",
      "include_user_stories": true,
      "priority": "high"
    }
  }'

Rate Limits​

API requests are rate limited based on your subscription plan:

PlanRequests per minuteConcurrent outcomes
Starter603
Growth30010
Pro100025
EnterpriseCustomCustom

Rate limit headers are included in all responses:

  • X-RateLimit-Limit: Request limit per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when limit resets

Error Handling​

HTTP Status Codes​

  • 200 - Success
  • 201 - Created (new resource)
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Internal Server Error

Error Response Format​

{
  "error": {
    "code": "invalid_brief",
    "message": "Brief must be at least 10 characters long",
    "details": {
      "field": "brief",
      "min_length": 10,
      "provided_length": 5
    }
  }
}

Pagination​

List endpoints support cursor-based pagination:

GET /v1/outcomes?limit=20&cursor=eyJpZCI6Im91dF8xMjM0NTY3ODkwIn0

Response:

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6Im91dF8wOTg3NjU0MzIxIn0",
    "has_more": true
  }
}

Best Practices​

1. Use Webhooks for Long-Running Operations​

Don't poll for outcome completion. Set up webhooks for real-time notifications.

2. Implement Retry Logic​

Handle transient errors with exponential backoff:

async function deployWithRetry(crew, params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.crews.deploy(crew, params);
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, i) * 1000)
        );
        continue;
      }
      throw error;
    }
  }
}

3. Validate Inputs Client-Side​

Check required fields before making API calls to reduce errors.

4. Store Outcome IDs​

Always store outcome IDs in your database for tracking and retrieval.

Support​

Next Steps: