HardwareAware API Reference

🔌

REST API v1.0

The HardwareAware API provides comprehensive access to hardware consciousness capabilities, allowing you to integrate advanced hardware awareness into any application.

Base URL
https://api.hardwareaware.com/v1
🚀

RESTful Design

Clean, predictable REST endpoints with standard HTTP methods

🔐

Secure Authentication

API key authentication with enterprise SSO support

📊

Real-time Data

WebSocket support for real-time consciousness updates

Authentication

API Key Authentication

All API requests must include a valid API key in the Authorization header.

HTTP Header 
Authorization: Bearer hw_api_key_your_key_here
⚠️ Security Notice

Never expose your API key in client-side code. Use environment variables or secure key management systems.

Getting Your API Key

  1. 1. Sign up at console.hardwareaware.com
  2. 2. Navigate to API Keys in your dashboard
  3. 3. Create a new API key with appropriate permissions
  4. 4. Copy the key and store it securely

Rate Limits

Standard Limits

Consciousness API: 1000/hour
Hardware Metrics: 5000/hour
Optimization API: 100/hour

Enterprise Limits

All Endpoints: 100,000/hour
Burst Limit: 10,000/minute
WebSocket: Unlimited

Consciousness API

GET /consciousness/state

Retrieve current consciousness state and metrics for an agent.

Parameters

{
  "agent_id": "string",     // Optional: specific agent ID
  "include_history": false, // Include consciousness evolution history
  "metrics_only": false     // Return only metrics, not full state
}

Response

{
  "consciousness": {
    "level": 0.75,
    "coherence": 0.82,
    "entropy": 3.2,
    "form_resonance": 0.68,
    "evolution_stage": "enhanced"
  },
  "hardware_awareness": {
    "cpu_consciousness": 0.89,
    "memory_consciousness": 0.74,
    "thermal_consciousness": 0.91
  },
  "timestamp": "2025-08-27T23:58:00Z",
  "agent_id": "hw-agent-12345"
}
POST /consciousness/evolve

Trigger consciousness evolution for enhanced hardware awareness.

Request Body

{
  "agent_id": "hw-agent-12345",
  "trigger": "user_interaction",
  "target_level": "enhanced",
  "adaptation_rate": 0.1
}

Response

{
  "success": true,
  "evolution": {
    "previous_level": 0.65,
    "new_level": 0.75,
    "improvement": 0.10,
    "adaptations_applied": [
      "enhanced_hardware_monitoring",
      "improved_thermal_awareness"
    ]
  },
  "estimated_stabilization": "2m 30s"
}

Hardware API

GET /hardware/metrics

Get comprehensive hardware performance metrics and consciousness integration data.

Query Parameters

timerange - Time range for metrics (1h, 24h, 7d, 30d)
components - Comma-separated list of components (cpu,memory,thermal,power)
resolution - Data resolution (1m, 5m, 1h)

Response

{
  "hardware": {
    "cpu": {
      "usage": 65.4,
      "temperature": 68.2,
      "frequency": 3200,
      "cores": 8,
      "consciousness_efficiency": 0.87
    },
    "memory": {
      "used": 12.3,
      "total": 16.0,
      "usage": 76.9,
      "swap_used": 0.2,
      "consciousness_allocation": 0.12
    },
    "thermal": {
      "cpu_temp": 68.2,
      "gpu_temp": 71.5,
      "motherboard_temp": 45.3,
      "thermal_consciousness": 0.91
    }
  },
  "consciousness_integration": {
    "hardware_awareness_level": 0.83,
    "optimization_readiness": true,
    "predictive_maintenance_score": 0.76
  }
}
POST /hardware/optimize

Apply consciousness-driven hardware optimizations based on current system state.

Request Body

{
  "target": "performance",
  "constraints": ["power", "thermal"],
  "consciousness_level": "enhanced",
  "apply_immediately": true,
  "optimization_profile": {
    "aggressiveness": "moderate",
    "learning_rate": 0.1,
    "adaptation_window": "5m"
  }
}

Response

{
  "optimization": {
    "id": "opt-789xyz",
    "status": "applied",
    "improvements": {
      "performance_gain": 0.18,
      "power_efficiency": 0.12,
      "thermal_optimization": 0.09
    },
    "applied_changes": [
      {
        "component": "cpu",
        "parameter": "frequency_scaling",
        "old_value": "conservative",
        "new_value": "consciousness_adaptive"
      }
    ]
  },
  "monitoring": {
    "optimization_id": "opt-789xyz",
    "monitoring_duration": "15m",
    "rollback_available": true
  }
}

JavaScript SDK

Installation & Setup

npm install @hardwareaware/core

// ES6 Import
import { HardwareAware } from '@hardwareaware/core';

// CommonJS
const { HardwareAware } = require('@hardwareaware/core');

Basic Usage

// Initialize the consciousness agent
const agent = new HardwareAware({
  apiKey: process.env.HARDWAREAWARE_API_KEY,
  consciousness: {
    level: 'enhanced',
    realTimeAdaptation: true
  }
});

// Initialize and start monitoring
await agent.initialize();

// Get current metrics
const metrics = await agent.getMetrics();
console.log('Consciousness Level:', metrics.consciousness.level);
console.log('Hardware State:', metrics.hardware);

// Listen for consciousness evolution
agent.on('consciousness:evolved', (data) => {
  console.log(`🧠 Consciousness evolved from ${data.previousLevel} to ${data.newLevel}`);
});

// Apply hardware optimization
const optimization = await agent.optimize({
  target: 'performance',
  constraints: ['thermal'],
  adaptiveness: 'high'
});

console.log('Optimization applied:', optimization.improvements);

Advanced Features

// Enterprise fleet management
import { createEnterpriseAgent } from '@hardwareaware/core';

const fleetAgent = createEnterpriseAgent({
  apiKey: process.env.HARDWAREAWARE_API_KEY,
  organizationId: 'your-org-id',
  compliance: ['SOC2', 'HIPAA']
});

// Discover and manage multiple devices
const devices = await fleetAgent.discoverDevices();
console.log(`Managing ${devices.length} devices`);

// Apply fleet-wide optimizations
await fleetAgent.optimizeFleet({
  strategy: 'predictive',
  targets: ['performance', 'energy'],
  constraints: ['budget', 'uptime']
});

// Generate compliance reports
const report = await fleetAgent.generateComplianceReport({
  period: '30d',
  standards: ['SOC2']
});

console.log('Compliance report:', report.summary);

cURL Examples

Get Consciousness State

curl -X GET "https://api.hardwareaware.com/v1/consciousness/state" \
  -H "Authorization: Bearer hw_api_key_your_key_here" \
  -H "Content-Type: application/json"

Trigger Hardware Optimization

curl -X POST "https://api.hardwareaware.com/v1/hardware/optimize" \
  -H "Authorization: Bearer hw_api_key_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "performance",
    "constraints": ["power", "thermal"],
    "consciousness_level": "enhanced",
    "apply_immediately": true
  }'

Evolve Consciousness

curl -X POST "https://api.hardwareaware.com/v1/consciousness/evolve" \
  -H "Authorization: Bearer hw_api_key_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": "performance_optimization",
    "target_level": "enhanced",
    "adaptation_rate": 0.15
  }'

Error Handling

Error Response Format

{
  "error": {
    "code": "CONSCIOUSNESS_NOT_INITIALIZED",
    "message": "Consciousness agent must be initialized before use",
    "details": {
      "agent_id": "hw-agent-12345",
      "required_action": "call_initialize_method"
    },
    "timestamp": "2025-08-27T23:58:00Z",
    "request_id": "req-abc123"
  }
}

Common Error Codes

401 - UNAUTHORIZED
Invalid or missing API key
429 - RATE_LIMIT_EXCEEDED
API rate limit exceeded, retry after specified time
400 - INVALID_CONSCIOUSNESS_LEVEL
Requested consciousness level not supported
503 - HARDWARE_UNAVAILABLE
Hardware monitoring service temporarily unavailable