Swarm Agent Ai API

Welcome to the Swarm Agent Ai API documentation. This comprehensive guide will help you integrate our multi-agent system into your applications and workflows.

Getting Started

The Swarm Agent Ai API allows you to leverage our sophisticated multi-agent system to process complex tasks through a RESTful interface. Each request is processed through our specialized agent pipeline, ensuring optimal results for your specific use case.

Base URL

https://swarmagentsai.com/v1

Rate Limits

  • Free Tier: 100 requests per hour
  • Pro Tier: 1,000 requests per hour
  • Enterprise: Custom limits available

Authentication

The Swarm Agent Ai API uses API key authentication. Include your API key in the Authorization header of your requests.

API Key Format

Authorization: Bearer YOUR_API_KEY

Security Notice

Keep your API key secure and never expose it in client-side code. Store it securely on your server and use environment variables.

Getting Your API Key

  1. Sign up for an Swarm Agent Ai account
  2. Navigate to your dashboard
  3. Go to API Keys section
  4. Generate a new API key
  5. Copy and store it securely

Endpoints

POST /process

Process a task through the Swarm Agent Ai pipeline

Parameters

Parameter Type Required Description
task string Yes The task description to be processed
priority string No Task priority: low, medium, high (default: medium)
agents array No Specific agents to use (default: all agents)
callback_url string No URL to receive completion webhook
GET /status/{task_id}

Check the status of a processing task

Path Parameters

Parameter Type Description
task_id string Unique identifier for the task
GET /results/{task_id}

Retrieve the results of a completed task

Path Parameters

Parameter Type Description
task_id string Unique identifier for the task

Request Example

Processing a Task

curl -X POST https://swarmagentsai.com/v1/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Write a comprehensive market analysis report for electric vehicles in 2025",
    "priority": "high",
    "agents": ["preprocessor", "planner", "researcher", "reasoner", "writer", "reviewer", "finalizer"],
    "callback_url": "https://your-domain.com/webhook"
  }'

JavaScript Example

const response = await fetch('https://swarmagentsai.com/v1/process', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    task: 'Write a comprehensive market analysis report for electric vehicles in 2025',
    priority: 'high',
    agents: ['preprocessor', 'planner', 'researcher', 'reasoner', 'writer', 'reviewer', 'finalizer'],
    callback_url: 'https://your-domain.com/webhook'
  })
});

const data = await response.json();

Python Example

import requests

url = "https://swarmagentsai.com/v1/process"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "task": "Write a comprehensive market analysis report for electric vehicles in 2025",
    "priority": "high",
    "agents": ["preprocessor", "planner", "researcher", "reasoner", "writer", "reviewer", "finalizer"],
    "callback_url": "https://your-domain.com/webhook"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

Response

Successful Response

{
  "success": true,
  "task_id": "task_12345",
  "status": "processing",
  "estimated_completion": "2025-01-15T14:30:00Z",
  "agents_assigned": [
    "preprocessor",
    "planner", 
    "researcher",
    "reasoner",
    "writer",
    "reviewer",
    "finalizer"
  ],
  "orchestrator_status": "active"
}

Task Status Response

{
  "task_id": "task_12345",
  "status": "completed",
  "progress": 100,
  "agents_progress": {
    "preprocessor": "completed",
    "planner": "completed",
    "researcher": "completed", 
    "reasoner": "completed",
    "writer": "completed",
    "reviewer": "completed",
    "finalizer": "completed"
  },
  "started_at": "2025-01-15T14:00:00Z",
  "completed_at": "2025-01-15T14:28:30Z"
}

Task Results Response

{
  "task_id": "task_12345",
  "status": "completed",
  "results": {
    "final_output": "Comprehensive market analysis report content...",
    "agent_outputs": {
      "preprocessor": "Task analysis and data preparation complete",
      "planner": "Strategic execution plan created", 
      "researcher": "Market data and trends gathered",
      "reasoner": "Analysis and insights generated",
      "writer": "Report content created",
      "reviewer": "Quality assurance completed",
      "finalizer": "Final formatting and polish applied"
    },
    "metadata": {
      "processing_time": "28.5 seconds",
      "tokens_used": 15420,
      "confidence_score": 0.95
    }
  }
}

Errors

The Swarm Agent Ai API uses conventional HTTP response codes to indicate success or failure.

HTTP Status Codes

200 - OK: Request successful
201 - Created: Task created successfully
400 - Bad Request: Invalid request parameters
401 - Unauthorized: Invalid or missing API key
403 - Forbidden: API key doesn't have required permissions
404 - Not Found: Resource not found
429 - Too Many Requests: Rate limit exceeded
500 - Internal Server Error: Server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_TASK",
    "message": "The provided task description is invalid or empty",
    "details": "Task must be between 10 and 5000 characters"
  },
  "request_id": "req_12345"
}

Common Error Codes

INVALID_API_KEY

The provided API key is invalid or has been revoked

RATE_LIMIT_EXCEEDED

You have exceeded your rate limit. Please wait before making more requests

INVALID_TASK

The task description is invalid, empty, or exceeds length limits

INSUFFICIENT_CREDITS

Your account doesn't have sufficient credits to process this request

TASK_NOT_FOUND

The specified task ID was not found