Skip to content

API Reference

Jump to bottom
Haveapp1 edited this page Aug 22, 2025 · 1 revision

API Reference

Complete programmatic interfaces for Agentwise integration and automation.

Overview

Agentwise provides comprehensive APIs for programmatic access to all system functionality. This includes agent management, task orchestration, configuration, and monitoring capabilities.

Core APIs

Agent Management API

List Available Agents

GET /api/v1/agents

// Response
{
  "agents": [
    {
      "id": "frontend-specialist",
      "name": "Frontend Specialist",
      "status": "active",
      "capabilities": ["react", "vue", "angular"],
      "current_load": 0.65,
      "tasks_completed": 156,
      "success_rate": 0.94
    }
  ],
  "total": 8,
  "active": 6
}

Get Agent Details

GET /api/v1/agents/{agent_id}

// Response
{
  "id": "frontend-specialist",
  "name": "Frontend Specialist",
  "description": "Expert in frontend development and UI/UX",
  "capabilities": {
    "technologies": ["react", "vue", "angular", "svelte"],
    "skills": ["component-design", "state-management", "responsive-design"],
    "tools": ["webpack", "vite", "tailwind", "styled-components"]
  },
  "configuration": {
    "max_concurrent_tasks": 3,
    "timeout": 300,
    "priority": "high"
  },
  "metrics": {
    "uptime": "99.8%",
    "avg_response_time": "12s",
    "success_rate": 0.94,
    "tasks_completed": 156
  }
}

Create Custom Agent

POST /api/v1/agents
Content-Type: application/json

{
  "name": "mobile-specialist",
  "description": "Mobile application development expert",
  "capabilities": {
    "technologies": ["react-native", "flutter", "swift", "kotlin"],
    "skills": ["mobile-ui", "native-apis", "app-store-deployment"]
  },
  "configuration": {
    "max_concurrent_tasks": 2,
    "timeout": 400,
    "priority": "medium"
  }
}

// Response
{
  "id": "mobile-specialist-001",
  "status": "created",
  "message": "Agent created successfully"
}

Task Management API

Create Task

POST /api/v1/tasks
Content-Type: application/json

{
  "description": "Create a React component for user authentication",
  "type": "frontend",
  "priority": "high",
  "requirements": {
    "framework": "react",
    "styling": "tailwindcss",
    "validation": "formik"
  },
  "context": {
    "project_type": "web-application",
    "existing_components": ["Button", "Input", "Modal"]
  },
  "deadline": "2024-01-15T10:00:00Z",
  "token_budget": 5000
}

// Response
{
  "task_id": "task-12345",
  "status": "queued",
  "estimated_completion": "2024-01-15T09:45:00Z",
  "assigned_agent": "frontend-specialist",
  "token_estimate": 4200
}

Get Task Status

GET /api/v1/tasks/{task_id}

// Response
{
  "task_id": "task-12345",
  "status": "in_progress",
  "progress": 0.65,
  "assigned_agent": "frontend-specialist",
  "created_at": "2024-01-15T09:00:00Z",
  "started_at": "2024-01-15T09:05:00Z",
  "estimated_completion": "2024-01-15T09:45:00Z",
  "token_usage": {
    "used": 2730,
    "budgeted": 5000,
    "remaining": 2270
  },
  "output_preview": "Generated AuthForm component with validation..."
}

List Tasks

GET /api/v1/tasks?status=active&limit=50&offset=0

// Response
{
  "tasks": [
    {
      "task_id": "task-12345",
      "status": "in_progress",
      "type": "frontend",
      "priority": "high",
      "assigned_agent": "frontend-specialist",
      "progress": 0.65,
      "created_at": "2024-01-15T09:00:00Z"
    }
  ],
  "total": 25,
  "has_more": true
}

Project Orchestration API

Initialize Project

POST /api/v1/projects
Content-Type: application/json

{
  "name": "ecommerce-platform",
  "type": "web-application",
  "description": "Full-stack e-commerce platform with React and Node.js",
  "requirements": {
    "frontend": {
      "framework": "react",
      "styling": "tailwindcss",
      "state_management": "zustand"
    },
    "backend": {
      "framework": "express",
      "database": "postgresql",
      "authentication": "jwt"
    },
    "features": [
      "user_authentication",
      "product_catalog",
      "shopping_cart",
      "payment_processing",
      "order_management"
    ]
  },
  "constraints": {
    "budget": 150000,
    "deadline": "2024-01-20T00:00:00Z",
    "quality_level": "production"
  }
}

// Response
{
  "project_id": "proj-67890",
  "status": "initialized",
  "estimated_tasks": 18,
  "required_agents": ["frontend", "backend", "database", "testing"],
  "estimated_completion": "2024-01-19T18:00:00Z",
  "token_estimate": 142000
}

Get Project Status

GET /api/v1/projects/{project_id}

// Response
{
  "project_id": "proj-67890",
  "name": "ecommerce-platform",
  "status": "in_progress",
  "progress": {
    "overall": 0.42,
    "by_phase": {
      "setup": 1.0,
      "development": 0.65,
      "testing": 0.0,
      "deployment": 0.0
    },
    "by_agent": {
      "frontend-specialist": 0.38,
      "backend-specialist": 0.55,
      "database-specialist": 0.80
    }
  },
  "tasks": {
    "total": 18,
    "completed": 7,
    "in_progress": 4,
    "pending": 7
  },
  "metrics": {
    "token_usage": {
      "used": 58420,
      "budgeted": 150000,
      "efficiency": 0.89
    },
    "time_spent": "2h 15m",
    "estimated_remaining": "3h 45m"
  }
}

Configuration API

Get Configuration

GET /api/v1/config

// Response
{
  "project": {
    "name": "my-project",
    "type": "web-application"
  },
  "agents": {
    "max_concurrent": 3,
    "timeout": 300
  },
  "tokens": {
    "budget": 100000,
    "optimization": true
  },
  "mcp": {
    "auto_discovery": true,
    "servers_count": 12
  }
}

Update Configuration

PATCH /api/v1/config
Content-Type: application/json

{
  "agents": {
    "max_concurrent": 5
  },
  "tokens": {
    "budget": 150000
  }
}

// Response
{
  "status": "updated",
  "changes": [
    "agents.max_concurrent: 3 → 5",
    "tokens.budget: 100000 → 150000"
  ]
}

Monitoring API

System Metrics

GET /api/v1/metrics

// Response
{
  "system": {
    "uptime": "5d 12h 30m",
    "version": "1.0.0",
    "status": "healthy"
  },
  "agents": {
    "total": 8,
    "active": 6,
    "average_load": 0.72
  },
  "tasks": {
    "completed_today": 45,
    "success_rate": 0.94,
    "average_completion_time": "4.2m"
  },
  "tokens": {
    "used_today": 125420,
    "efficiency": 0.87,
    "cost_savings": 0.35
  }
}

Performance Analytics

GET /api/v1/analytics?period=7d&metrics=all

// Response
{
  "period": "7d",
  "summary": {
    "projects_completed": 12,
    "total_tasks": 286,
    "success_rate": 0.936,
    "average_project_time": "45m",
    "token_efficiency": 0.89
  },
  "trends": {
    "daily_completions": [8, 12, 15, 18, 22, 19, 16],
    "success_rates": [0.92, 0.94, 0.96, 0.93, 0.95, 0.94, 0.92],
    "token_usage": [85420, 92310, 78950, 105670, 89340, 76890, 82450]
  },
  "agent_performance": {
    "frontend-specialist": {
      "tasks_completed": 65,
      "success_rate": 0.95,
      "avg_completion_time": "3.8m"
    },
    "backend-specialist": {
      "tasks_completed": 58,
      "success_rate": 0.92,
      "avg_completion_time": "4.5m"
    }
  }
}

WebSocket API

Real-time updates via WebSocket connection:

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:3001/api/v1/ws');

// Subscribe to events
ws.send(JSON.stringify({
  "action": "subscribe",
  "events": ["task.progress", "agent.status", "project.update"]
}));

// Receive real-time updates
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Real-time update:', data);
};

// Example received message
{
  "event": "task.progress",
  "task_id": "task-12345",
  "progress": 0.75,
  "agent": "frontend-specialist",
  "timestamp": "2024-01-15T09:30:00Z"
}

SDK Libraries

JavaScript/Node.js SDK

npm install @agentwise/sdk
import { Agentwise } from '@agentwise/sdk';

const client = new Agentwise({
  apiKey: process.env.AGENTWISE_API_KEY,
  baseUrl: 'http://localhost:3001'
});

// Create and monitor a task
const task = await client.tasks.create({
  description: 'Build authentication system',
  type: 'full-stack',
  requirements: {
    frontend: 'react',
    backend: 'express',
    database: 'postgresql'
  }
});

// Monitor progress
for await (const update of client.tasks.watch(task.id)) {
  console.log(`Progress: ${update.progress * 100}%`);
  if (update.status === 'completed') {
    console.log('Task completed!', update.output);
    break;
  }
}

Python SDK

pip install agentwise-sdk
from agentwise import Agentwise

client = Agentwise(
    api_key=os.environ['AGENTWISE_API_KEY'],
    base_url='http://localhost:3001'
)

# Create project
project = client.projects.create({
    'name': 'mobile-app',
    'type': 'mobile-application',
    'requirements': {
        'platform': 'react-native',
        'features': ['auth', 'messaging', 'payments']
    }
})

# Monitor project progress
for update in client.projects.watch(project.id):
    print(f"Progress: {update.progress * 100:.1f}%")
    if update.status == 'completed':
        print(f"Project completed! Files: {len(update.files)}")
        break

CLI Integration

The CLI provides direct API access:

# Create task via CLI
agentwise task create \
  --description "Build user dashboard" \
  --type "frontend" \
  --priority "high" \
  --budget 8000

# Monitor task progress
agentwise task watch task-12345

# Get system status
agentwise status --json

# Export project
agentwise project export proj-67890 --format zip

Authentication

API Key Authentication

# Set API key as header
curl -H "Authorization: Bearer your-api-key" \
     -H "Content-Type: application/json" \
     http://localhost:3001/api/v1/agents

JWT Authentication

// Login to get JWT token
POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "password"
}

// Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

// Use token in subsequent requests
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Error Handling

Standard Error Format

{
  "error": {
    "code": "TASK_CREATION_FAILED",
    "message": "Unable to create task due to insufficient token budget",
    "details": {
      "required_budget": 5000,
      "available_budget": 2300,
      "suggestion": "Increase token budget or reduce task complexity"
    },
    "timestamp": "2024-01-15T09:30:00Z",
    "request_id": "req-abc123"
  }
}

Common Error Codes

  • INSUFFICIENT_BUDGET - Not enough tokens for operation
  • AGENT_UNAVAILABLE - Requested agent is offline
  • TASK_TIMEOUT - Task exceeded time limit
  • INVALID_CONFIGURATION - Configuration validation failed
  • QUOTA_EXCEEDED - API rate limit exceeded
  • AUTHENTICATION_FAILED - Invalid credentials

Rate Limiting

# Rate limit headers in response
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000
X-RateLimit-Retry-After: 60

Rate Limits by Endpoint

  • /api/v1/tasks - 100 requests/minute
  • /api/v1/agents - 200 requests/minute
  • /api/v1/projects - 50 requests/minute
  • /api/v1/metrics - 1000 requests/minute

API Versioning

Agentwise uses semantic versioning for APIs:

  • v1 - Current stable version
  • v2-beta - Next version in beta
  • v1-deprecated - Previous version (will be removed)
# Specify API version in URL
GET /api/v1/agents

# Or use Accept header
Accept: application/vnd.agentwise.v1+json

For more information, see Configuration, Agent System, or Architecture.

Navigation

🚀 Getting Started

📚 Documentation

🛠️ Development

🎯 Advanced Topics

📖 Resources

⚖️ Legal

🔗 Quick Links

Support

  • Discord: @vibecodingwithphil
  • GitHub: @VibeCodingWithPhil

Clone this wiki locally