Crew APIs

The Crew APIs allow you to programmatically deploy AI crews, monitor their execution, and manage outcomes. This is the core functionality for integrating HornetHive into your applications and workflows.

Available Crews

HornetHive provides three specialized AI crews:

HiveWriter: Content creation and publishing automation
HiveMind: Operations analysis and task coordination
HivePilot: Product management and development workflows

List Available Crews

Get information about all available crews and their current status.

GET /v1/crews

Response

{
  "crews": [
    {
      "id": "hivewriter",
      "name": "HiveWriter",
      "description": "Content creation and publishing automation",
      "agents": [
        "ResearchAgent",
        "ContentAgent", 
        "EditorAgent",
        "SEOAgent",
        "PublisherAgent"
      ],
      "status": "available",
      "capabilities": [
        "blog_posts",
        "social_media",
        "documentation",
        "marketing_content"
      ],
      "integrations": [
        "linkedin",
        "wordpress", 
        "google_drive",
        "notion"
      ]
    },
    {
      "id": "hivemind",
      "name": "HiveMind", 
      "description": "Operations analysis and task coordination",
      "agents": [
        "AnalystAgent",
        "CoordinatorAgent",
        "SummarizerAgent",
        "ActionAgent",
        "IntegrationAgent"
      ],
      "status": "available",
      "capabilities": [
        "meeting_analysis",
        "task_coordination",
        "performance_analytics",
        "process_optimization"
      ],
      "integrations": [
        "slack",
        "asana",
        "jira",
        "tableau"
      ]
    },
    {
      "id": "hivepilot",
      "name": "HivePilot",
      "description": "Product management and development workflows", 
      "agents": [
        "ProductAgent",
        "TechnicalAgent",
        "PlanningAgent",
        "TicketAgent",
        "ReleaseAgent"
      ],
      "status": "available",
      "capabilities": [
        "prd_generation",
        "roadmap_planning",
        "ticket_creation",
        "release_management"
      ],
      "integrations": [
        "jira",
        "github",
        "linear",
        "confluence"
      ]
    }
  ]
}

Deploy a Crew

Deploy a crew to generate an outcome based on your requirements.

POST /v1/crews/{crew_id}/deploy

Path Parameters

crew_id (string, required): The ID of the crew to deploy (hivewriter, hivemind, or hivepilot)

Request Body

{
  "brief": "Create a comprehensive blog post about AI automation for small businesses",
  "context": "Target audience: 10-50 person companies looking to scale operations",
  "requirements": {
    "tone": "professional but approachable",
    "length": "1500-2000 words",
    "format": "markdown",
    "include_examples": true,
    "seo_optimized": true
  },
  "template_id": "technical_blog_post",
  "integrations": {
    "publish_to_linkedin": true,
    "save_to_drive": true,
    "notify_slack": "#content-team"
  },
  "context_documents": [
    "company_style_guide.pdf",
    "previous_blog_posts.md"
  ]
}

Response

{
  "outcome_id": "out_1234567890abcdef",
  "status": "processing",
  "crew": "hivewriter",
  "estimated_completion": "2024-01-15T10:35:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "agents_deployed": [
    "ResearchAgent",
    "ContentAgent",
    "EditorAgent",
    "SEOAgent"
  ],
  "progress": {
    "current_stage": "research",
    "completion_percentage": 15,
    "next_stage": "content_creation"
  }
}

Crew-Specific Examples

HiveWriter Deployment

Create content with HiveWriter:

curl -X POST "https://api.hornethive.ai/v1/crews/hivewriter/deploy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Write a technical tutorial about Docker containerization",
    "context": "Developer audience, intermediate level",
    "requirements": {
      "tone": "technical but accessible",
      "length": "2000-2500 words",
      "include_code_examples": true,
      "format": "markdown"
    },
    "integrations": {
      "publish_to_linkedin": true,
      "save_to_notion": true
    }
  }'

HiveMind Deployment

Analyze operations with HiveMind:

curl -X POST "https://api.hornethive.ai/v1/crews/hivemind/deploy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Analyze last weeks team meetings and extract action items",
    "context": "Engineering team, 5 meetings, focus on sprint planning",
    "requirements": {
      "format": "executive_summary",
      "include_action_items": true,
      "priority_ranking": true
    },
    "context_documents": [
      "meeting_recordings.zip",
      "sprint_backlog.csv"
    ],
    "integrations": {
      "create_jira_tickets": true,
      "notify_slack": "#engineering"
    }
  }'

HivePilot Deployment

Generate product documentation with HivePilot:

curl -X POST "https://api.hornethive.ai/v1/crews/hivepilot/deploy" \
  -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, need real-time notifications",
    "requirements": {
      "format": "standard_prd",
      "include_user_stories": true,
      "include_technical_specs": true,
      "priority": "high"
    },
    "integrations": {
      "create_github_issues": true,
      "save_to_confluence": true
    }
  }'

Monitor Crew Execution

Get Outcome Status

Check the status of a deployed crew:

GET /v1/outcomes/{outcome_id}

Response

{
  "id": "out_1234567890abcdef",
  "status": "processing",
  "crew": "hivewriter",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_completion": "2024-01-15T10:35:00Z",
  "progress": {
    "current_stage": "content_creation",
    "completion_percentage": 65,
    "stages_completed": [
      "research",
      "outline_creation"
    ],
    "current_agent": "ContentAgent",
    "next_stage": "editing"
  },
  "agents": {
    "ResearchAgent": {
      "status": "completed",
      "completion_time": "2024-01-15T10:32:15Z",
      "output_summary": "Gathered 15 relevant sources on AI automation"
    },
    "ContentAgent": {
      "status": "processing", 
      "started_at": "2024-01-15T10:32:20Z",
      "progress": "Creating main content sections"
    }
  }
}

Real-Time Updates

For real-time updates, use WebSocket connections:

const ws = new WebSocket('wss://api.hornethive.ai/v1/outcomes/out_1234567890abcdef/stream');

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log('Progress update:', update);
};

Outcome Management

Get Completed Outcome

Retrieve the final result when crew execution is complete:

GET /v1/outcomes/{outcome_id}/result

Response

{
  "id": "out_1234567890abcdef",
  "status": "completed",
  "crew": "hivewriter",
  "completed_at": "2024-01-15T10:33:24Z",
  "result": {
    "content": "# AI Automation for Small Businesses\n\nIn today's competitive landscape...",
    "metadata": {
      "word_count": 1847,
      "reading_time": "7 minutes",
      "seo_score": 85,
      "readability_score": 72
    },
    "assets": [
      {
        "type": "image",
        "url": "https://cdn.hornethive.ai/outcomes/out_123.../hero-image.png",
        "description": "AI automation workflow diagram"
      }
    ]
  },
  "integrations_executed": {
    "linkedin": {
      "status": "completed",
      "post_url": "https://linkedin.com/posts/...",
      "engagement": {
        "views": 1250,
        "likes": 45,
        "comments": 8
      }
    },
    "google_drive": {
      "status": "completed", 
      "file_url": "https://drive.google.com/file/d/...",
      "file_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
    }
  },
  "quality_metrics": {
    "overall_score": 92,
    "criteria": {
      "relevance": 95,
      "clarity": 88,
      "completeness": 94,
      "engagement": 91
    }
  }
}

Request Revision

Request changes to a completed outcome:

POST /v1/outcomes/{outcome_id}/revise

Request Body

{
  "feedback": "Make the tone more casual and add more specific examples of automation tools",
  "requirements": {
    "tone": "casual",
    "examples": "at least 5 specific tools with use cases",
    "length": "maintain current length"
  },
  "priority": "high"
}

Response

{
  "revision_id": "rev_0987654321fedcba",
  "status": "processing",
  "estimated_completion": "2024-01-15T11:15:00Z",
  "changes_requested": [
    "tone_adjustment",
    "add_examples",
    "maintain_length"
  ]
}

Batch Operations

Deploy Multiple Crews

Deploy multiple crews for complex workflows:

POST /v1/crews/batch-deploy

Request Body

{
  "workflow_name": "Product Launch Campaign",
  "crews": [
    {
      "crew_id": "hivepilot",
      "brief": "Create PRD for new feature launch",
      "priority": 1
    },
    {
      "crew_id": "hivewriter", 
      "brief": "Create launch blog post and social content",
      "priority": 2,
      "depends_on": ["hivepilot"]
    },
    {
      "crew_id": "hivemind",
      "brief": "Create launch coordination plan and track metrics",
      "priority": 3,
      "depends_on": ["hivewriter"]
    }
  ]
}

List Your Outcomes

Get all outcomes for your account:

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

Query Parameters

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

Error Handling

Common Errors

400 Bad Request - Invalid Brief:

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

402 Payment Required - Insufficient Credits:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough outcomes remaining in your plan",
    "details": {
      "outcomes_remaining": 0,
      "outcomes_required": 1,
      "upgrade_url": "https://app.hornethive.ai/billing"
    }
  }
}

409 Conflict - Crew Unavailable:

{
  "error": {
    "code": "crew_unavailable",
    "message": "HiveWriter crew is temporarily unavailable",
    "details": {
      "crew": "hivewriter",
      "estimated_availability": "2024-01-15T11:00:00Z",
      "alternative_crews": ["hivemind"]
    }
  }
}

Best Practices

1. Provide Clear Briefs

✅ Good Brief:

{
  "brief": "Write a comprehensive guide about implementing CI/CD pipelines for React applications, targeting mid-level developers who are new to DevOps practices"
}

❌ Poor Brief:

{
  "brief": "Write about CI/CD"
}

2. Use Context Documents

Upload relevant context to improve outcome quality:

{
  "context_documents": [
    "company_style_guide.pdf",
    "previous_successful_posts.md",
    "target_audience_research.docx"
  ]
}

3. Set Realistic Requirements

Be specific but realistic with your requirements:

{
  "requirements": {
    "tone": "professional but approachable",
    "length": "1500-2000 words",
    "include_code_examples": true,
    "seo_optimized": true,
    "target_keywords": ["CI/CD", "React", "DevOps"]
  }
}

4. Monitor Progress

Use webhooks or polling to monitor crew execution:

// Polling example
async function waitForCompletion(outcomeId) {
  while (true) {
    const outcome = await fetch(`/v1/outcomes/${outcomeId}`);
    const data = await outcome.json();
    
    if (data.status === 'completed') {
      return data;
    } else if (data.status === 'failed') {
      throw new Error('Crew execution failed');
    }
    
    await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30s
  }
}

SDKs and Examples

Node.js SDK

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

const client = new HornetHive(process.env.HORNETHIVE_API_KEY);

// Deploy HiveWriter
const outcome = await client.crews.deploy('hivewriter', {
  brief: 'Write a blog post about sustainable technology',
  requirements: {
    tone: 'informative',
    length: '1200-1500 words'
  }
});

// Monitor progress
const result = await client.outcomes.waitForCompletion(outcome.id);
console.log('Content created:', result.content);

Python SDK

from hornethive import HornetHive

client = HornetHive(os.getenv('HORNETHIVE_API_KEY'))

# Deploy HivePilot
outcome = client.crews.deploy('hivepilot', {
    'brief': 'Create PRD for mobile app feature',
    'requirements': {
        'format': 'standard_prd',
        'include_user_stories': True
    }
})

# Get result
result = client.outcomes.get(outcome.id)
print(f"PRD created: {result.content}")

Next Steps:

Webhooks - Set up real-time notifications
Authentication - Secure your API access
Integration Guides - Connect your tools

Available Crews​

List Available Crews​

Response​

Deploy a Crew​

Path Parameters​

Request Body​

Response​

Crew-Specific Examples​

HiveWriter Deployment​

HiveMind Deployment​

HivePilot Deployment​

Monitor Crew Execution​

Get Outcome Status​

Response​

Real-Time Updates​

Outcome Management​

Get Completed Outcome​

Response​

Request Revision​

Request Body​

Response​

Batch Operations​

Deploy Multiple Crews​

Request Body​

List Your Outcomes​

Query Parameters​

Error Handling​

Common Errors​

Best Practices​

1. Provide Clear Briefs​

2. Use Context Documents​

3. Set Realistic Requirements​

4. Monitor Progress​

SDKs and Examples​

Node.js SDK​

Python SDK​

Available Crews

List Available Crews

Response

Deploy a Crew

Path Parameters

Request Body

Response

Crew-Specific Examples

HiveWriter Deployment

HiveMind Deployment

HivePilot Deployment

Monitor Crew Execution

Get Outcome Status

Response

Real-Time Updates

Outcome Management

Get Completed Outcome

Response

Request Revision

Request Body

Response

Batch Operations

Deploy Multiple Crews

Request Body

List Your Outcomes

Query Parameters

Error Handling

Common Errors

Best Practices

1. Provide Clear Briefs

2. Use Context Documents

3. Set Realistic Requirements

4. Monitor Progress

SDKs and Examples

Node.js SDK

Python SDK