📡 RedQuanta MCP REST API Reference¶

![API Version](https://img.shields.io/badge/API%20Version-v1.0-blue?style=for-the-badge&logo=fastify) ![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0-green?style=for-the-badge&logo=swagger) ![Response Format](https://img.shields.io/badge/Format-JSON-orange?style=for-the-badge&logo=json) **🚀 Complete REST API Documentation for RedQuanta MCP** *Professional penetration testing orchestration via HTTP/REST*

🎯 API Overview¶

🏗️ Architecture¶

┌─────────────────┐    HTTP/HTTPS    ┌─────────────────┐
│                 │ ──────────────► │                 │
│   Client App    │                 │  RedQuanta MCP  │
│                 │ ◄────────────── │   REST Server   │
└─────────────────┘    JSON/SARIF   └─────────────────┘
        │                                     │
        │                                     │
        ▼                                     ▼
┌─────────────────┐                 ┌─────────────────┐
│   Web UI        │                 │   Security      │
│   CLI Tools     │                 │   Tools Engine  │
│   Automation    │                 │   Workflows     │
└─────────────────┘                 └─────────────────┘

📋 Base Configuration¶

Parameter	Value	Description
Base URL	`http://localhost:5891`	Default server address
Protocol	`HTTP/1.1`, `HTTP/2`	Supported protocols
Content-Type	`application/json`	Request/response format
Authentication	`Bearer Token` (optional)	API key authentication
Rate Limiting	`100 req/min`	Default rate limits

🔧 Quick Start¶

⚡ Test Your API Connection¶

🧪 cURL Examples

# Health check
curl -X GET "http://localhost:5891/health" \
  -H "Accept: application/json"

# List all tools
curl -X GET "http://localhost:5891/tools" \
  -H "Accept: application/json"

# Execute a network scan
curl -X POST "http://localhost:5891/tools/nmap_scan" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "127.0.0.1",
    "dangerous": false
  }'

🐍 Python Examples

import requests
import json

# Initialize client
base_url = "http://localhost:5891"
headers = {"Content-Type": "application/json"}

# Health check
response = requests.get(f"{base_url}/health")
print(f"Health: {response.json()}")

# List tools
tools = requests.get(f"{base_url}/tools").json()
print(f"Available tools: {len(tools['tools'])}")

# Execute scan
scan_request = {
    "target": "127.0.0.1",
    "dangerous": False
}
result = requests.post(
    f"{base_url}/tools/nmap_scan", 
    json=scan_request
).json()
print(f"Scan result: {result['success']}")

📜 JavaScript Examples

// Using fetch API
const API_BASE = 'http://localhost:5891';

// Health check
const health = await fetch(`${API_BASE}/health`)
  .then(res => res.json());
console.log('Health:', health);

// Execute enumeration workflow
const enumResult = await fetch(`${API_BASE}/enum`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    target: '192.168.1.0/24',
    scope: 'network',
    depth: 'light'
  })
}).then(res => res.json());

console.log('Enumeration:', enumResult);

🛠️ Core Endpoints¶

🏥 System & Health¶

Endpoint	Method	Description
`/health`	GET	🏥 System health check and status
`/config`	GET	⚙️ Server configuration and capabilities
`/version`	GET	📋 Version and build information
`/metrics`	GET	📊 Performance and usage metrics

🏥 GET /health¶

📝 Response Schema

{
  "status": "healthy",
  "version": "0.3.0",
  "platform": "win32",
  "dangerous": false,
  "timestamp": "2024-12-24T10:30:00.000Z",
  "uptime": 3600,
  "jailRoot": "C:\\Users\\%USERNAME%\\AppData\\Local\\RedQuanta\\vol",
  "toolsLoaded": 14,
  "capabilities": {
    "mcp": true,
    "rest": true,
    "plugins": true,
    "workflows": true
  }
}

⚙️ GET /config¶

📝 Response Schema

{
  "server": {
    "mode": "rest",
    "version": "0.3.0",
    "platform": "win32",
    "dangerousMode": false,
    "jailRoot": "C:\\Users\\%USERNAME%\\AppData\\Local\\RedQuanta\\vol"
  },
  "capabilities": {
    "totalTools": 14,
    "toolCategories": {
      "discovery": 2,
      "web": 3,
      "exploitation": 3,
      "workflow": 4,
      "system": 2
    }
  },
  "security": {
    "auditLogging": true,
    "pathValidation": true,
    "commandSanitization": true,
    "dangerousOperationsGated": true
  },
  "performance": {
    "cacheEnabled": true,
    "maxConcurrentJobs": 10,
    "requestTimeout": 300000
  }
}

🛠️ Tool Management¶

Endpoint	Method	Description
`/tools`	GET	📋 List all available tools with schemas
`/tools/{toolName}`	POST	⚡ Execute specific tool with parameters
`/tools/{toolName}/help`	GET	📚 Get detailed tool documentation
`/tools/{toolName}/schema`	GET	📐 Get tool input/output schema

📋 GET /tools¶

📝 Response Schema

{
  "success": true,
  "count": 14,
  "categories": {
    "discovery": ["nmap", "masscan"],
    "web": ["ffuf", "gobuster", "nikto"],
    "exploitation": ["sqlmap_test", "john_crack", "hydra_bruteforce"],
    "workflow": ["workflow_enum", "workflow_scan", "workflow_report"],
    "system": ["filesystem_ops", "command_run"]
  },
  "tools": [
    {
      "name": "nmap",
      "description": "Advanced network discovery and port scanning",
      "category": "discovery",
      "dangerous": false,
      "inputSchema": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string",
            "description": "Target IP, hostname, or CIDR range",
            "examples": ["192.168.1.10", "example.com", "10.0.0.0/24"]
          },
          "dangerous": {
            "type": "boolean",
            "description": "Enable dangerous/aggressive scanning",
            "default": false
          }
        },
        "required": ["target"]
      }
    }
  ]
}

⚡ POST /tools/{toolName}¶

📋 Request Examples

**Nmap Network Scan:**

{
  "target": "192.168.1.0/24",
  "dangerous": false,
  "custom_flags": ["-sS", "-T4"],
  "timeout": 300000
}

**FFUF Web Fuzzing:**

{
  "url": "https://example.com/FUZZ",
  "wordlist": "/usr/share/wordlists/dirb/common.txt",
  "dangerous": false,
  "custom_headers": {
    "Authorization": "Bearer token123"
  },
  "filter_codes": "404,403"
}

**Workflow Enumeration:**

{
  "target": "example.com",
  "scope": "full",
  "depth": "normal",
  "coaching": "beginner",
  "custom_options": {
    "nmap_flags": ["-sV", "-sC"],
    "timing_template": "T3"
  }
}

📝 Response Schema

{
  "success": true,
  "executionId": "exec_12345",
  "tool": "nmap",
  "target": "192.168.1.1",
  "startTime": "2024-12-24T10:30:00.000Z",
  "endTime": "2024-12-24T10:30:45.123Z",
  "duration": 45123,
  "data": {
    "hosts": [
      {
        "ip": "192.168.1.1",
        "hostname": "router.local",
        "status": "up",
        "ports": [
          {
            "port": 80,
            "protocol": "tcp",
            "state": "open",
            "service": "http",
            "version": "nginx/1.18.0"
          }
        ]
      }
    ],
    "summary": {
      "hostsUp": 1,
      "portsOpen": 1,
      "services": ["http"]
    }
  },
  "rawOutput": "# Nmap 7.80 scan initiated...",
  "metadata": {
    "command": "nmap -sT -T4 192.168.1.1",
    "dangerous": false,
    "cached": false
  },
  "recommendations": [
    "🔍 Scan revealed HTTP service on port 80",
    "⚡ Consider web application testing with FFUF or Nikto",
    "🛡️ Review server version for known vulnerabilities"
  ]
}

🤖 Workflow Automation¶

Endpoint	Method	Description
`/enum`	POST	🔍 Automated reconnaissance workflow
`/scan`	POST	🛡️ Vulnerability assessment workflow
`/report`	POST	📊 Professional report generation
`/workflows`	GET	📋 List available workflow templates

🔍 POST /enum¶

📋 Request Schema

{
  "target": "192.168.1.0/24",
  "scope": "network",
  "depth": "normal",
  "coaching": "beginner",
  "custom_options": {
    "nmap_flags": ["-sV", "-sC"],
    "timing_template": "T3",
    "wordlists": {
      "directories": "/usr/share/wordlists/dirb/common.txt",
      "subdomains": "/usr/share/wordlists/subdomains.txt"
    }
  }
}

🛡️ POST /scan¶

📋 Request Schema

{
  "target": "example.com",
  "services": ["http", "https", "ssh"],
  "aggressive": false,
  "coaching": "beginner",
  "scan_options": {
    "network_scan": {
      "os_detection": true,
      "version_detection": true,
      "script_scanning": true
    },
    "web_scan": {
      "directories": true,
      "vulnerabilities": true,
      "ssl_analysis": true
    },
    "database_scan": {
      "injection_testing": false,
      "brute_force": false
    }
  }
}

🔌 Plugin Management¶

Endpoint	Method	Description
`/plugins`	GET	🧩 List loaded plugins and their status
`/plugins/reload`	POST	🔄 Hot reload all plugins
`/plugins/{name}/info`	GET	ℹ️ Get detailed plugin information

🔐 Authentication & Security¶

🔑 API Authentication¶

Bearer Token Authentication

# Set API key in headers
curl -X GET "http://localhost:5891/tools" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"

**API Key Configuration:**

{
  "apiKey": "redquanta_ak_1234567890abcdef",
  "keyType": "bearer",
  "expiresAt": "2024-12-31T23:59:59Z",
  "permissions": ["read", "execute", "dangerous"]
}

🛡️ Security Headers¶

All API responses include security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000
Content-Security-Policy: default-src 'self'

📊 Response Formats¶

✅ Success Response¶

{
  "success": true,
  "data": { /* Tool-specific data */ },
  "metadata": {
    "executionId": "exec_12345",
    "timestamp": "2024-12-24T10:30:00.000Z",
    "duration": 1234,
    "cached": false
  },
  "recommendations": [
    "Next step suggestions..."
  ]
}

❌ Error Response¶

{
  "success": false,
  "error": {
    "code": "INVALID_TARGET",
    "message": "Target IP address is invalid",
    "details": "The provided target '999.999.999.999' is not a valid IP address",
    "timestamp": "2024-12-24T10:30:00.000Z",
    "requestId": "req_67890"
  },
  "documentation": "https://github.com/sc4rfurry/RedQuanta-MCP/docs/api/errors.md#invalid-target"
}

📈 Streaming Response¶

For long-running operations:

{
  "type": "progress",
  "executionId": "exec_12345",
  "phase": "host_discovery",
  "progress": 25,
  "message": "Discovered 5 hosts, scanning ports...",
  "timestamp": "2024-12-24T10:30:15.000Z"
}

🚨 Error Codes¶

Code	HTTP Status	Description
`INVALID_TARGET`	400 Bad Request	Target IP/hostname is invalid or malformed
`TOOL_NOT_FOUND`	404 Not Found	Requested tool is not available
`DANGEROUS_OPERATION`	403 Forbidden	Operation requires dangerous flag
`RATE_LIMITED`	429 Too Many Requests	Too many requests in time window
`EXECUTION_TIMEOUT`	408 Request Timeout	Tool execution exceeded timeout
`INTERNAL_ERROR`	500 Internal Server Error	Unexpected server error occurred

📈 Rate Limiting¶

🚦 Default Limits¶

Endpoint Category	Limit	Window	Burst
Health/Config	100 req/min	1 minute	10
Tool Listing	50 req/min	1 minute	5
Tool Execution	20 req/min	1 minute	3
Workflows	10 req/min	1 minute	2

📊 Rate Limit Headers¶

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
X-RateLimit-RetryAfter: 60

🧪 Testing & Development¶

🔬 API Testing¶

Postman Collection

{
  "info": {
    "name": "RedQuanta MCP API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Health Check",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/health"
      }
    },
    {
      "name": "List Tools",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/tools"
      }
    },
    {
      "name": "Nmap Scan",
      "request": {
        "method": "POST",
        "url": "{{baseUrl}}/tools/nmap",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"target\": \"127.0.0.1\",\n  \"dangerous\": false\n}"
        }
      }
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "value": "http://localhost:5891"
    }
  ]
}

📋 OpenAPI Specification¶

Full OpenAPI 3.0 specification available at: - Interactive Docs: http://localhost:5891/api/docs - JSON Spec: http://localhost:5891/api/openapi.json - YAML Spec: http://localhost:5891/api/openapi.yaml

📞 Support & Resources¶

🆘 Getting Help¶

[![GitHub Issues](https://img.shields.io/badge/🐛-Report%20API%20Bug-red?style=for-the-badge)](https://github.com/sc4rfurry/RedQuanta-MCP/issues/new?template=api_bug.md) [![API Questions](https://img.shields.io/badge/❓-API%20Questions-blue?style=for-the-badge)](https://github.com/sc4rfurry/RedQuanta-MCP/discussions/categories/api) [![Feature Request](https://img.shields.io/badge/💡-Request%20Feature-green?style=for-the-badge)](https://github.com/sc4rfurry/RedQuanta-MCP/issues/new?template=api_feature.md)

📚 Additional Resources¶

📖 MCP Protocol Guide - Model Context Protocol documentation
🧩 Plugin Development - Create custom tools
🔒 Security Guide - Security best practices
🚨 Troubleshooting - Common API issues

**📡 API Version 1.0** ![Build Status](https://img.shields.io/badge/Build-Passing-success?style=for-the-badge) ![API Tests](https://img.shields.io/badge/API%20Tests-100%25-brightgreen?style=for-the-badge) ![Response Time](https://img.shields.io/badge/Response%20Time-<100ms-blue?style=for-the-badge) **Made with 🚀 by [@sc4rfurry](https://github.com/sc4rfurry)** *Powerful APIs for intelligent security automation*