Skip to main content

API Reference

The Aida Platform API provides comprehensive endpoints for managing smart buildings, devices, and users. Built with RESTful principles and documented using OpenAPI 3.0 specification.

Base URL​

  • Development: http://localhost:8000/api
  • Production: https://api.aida-platform.com/api

Authentication​

All API requests require authentication using JWT Bearer tokens:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     https://api.aida-platform.com/api/devices

Response Format​

All API responses follow a consistent format:

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Operation completed successfully",
  "error": null
}

Error Handling​

Standard Error Response​

{
  "success": false,
  "data": null,
  "message": "Error description",
  "error": "Detailed error information"
}

HTTP Status Codes​

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

API Categories​

🔐 Authentication​

Manage user authentication and authorization:

  • User registration and login
  • Password reset and recovery
  • JWT token management
  • Role-based access control

🏢 Building Management​

Control building structure and organization:

  • Buildings, floors, and zones
  • Space planning and layout
  • Occupancy management
  • Environmental monitoring

🔌 Device Management​

Control and monitor smart devices:

  • FMP Devices: Fault Managed Power systems
  • Network Switches: Cisco switch integration
  • HVAC Systems: Heating, ventilation, air conditioning
  • Lighting: Smart lighting controls
  • Shades: Automated window treatments
  • Sensors: Environmental and occupancy sensors

📊 Analytics & Reporting​

Access data insights and reports:

  • Energy consumption analytics
  • Occupancy patterns
  • Maintenance schedules
  • Performance metrics

🤖 AI & Automation​

Leverage AI-powered features:

  • Predictive maintenance
  • Energy optimization
  • Automated scheduling
  • Voice assistant integration

Interactive Documentation​

Swagger UI​

Access our interactive API documentation:

Features​

  • Try It Out: Test endpoints directly in the browser
  • Request/Response Examples: See real examples for each endpoint
  • Schema Validation: Automatic validation of request/response formats
  • Authentication: Built-in JWT token testing

Code Generation​

Generate client SDKs in multiple languages:

JavaScript/TypeScript​

npx @openapitools/openapi-generator-cli generate \
  -i https://api.aida-platform.com/api-docs/swagger.json \
  -g typescript-fetch \
  -o ./generated-client

Python​

npx @openapitools/openapi-generator-cli generate \
  -i https://api.aida-platform.com/api-docs/swagger.json \
  -g python \
  -o ./generated-python-client

cURL Examples​

# Get all devices
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.aida-platform.com/api/devices

# Control a light
curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"state": "on", "brightness": 80}' \
     https://api.aida-platform.com/api/devices/lights/123/control

# Get energy report
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://api.aida-platform.com/api/reports/energy?start=2024-01-01&end=2024-01-31"

Rate Limiting​

API requests are rate limited to ensure fair usage:

  • Authentication: 5 requests per minute
  • Device Control: 100 requests per minute
  • Data Queries: 1000 requests per hour
  • Bulk Operations: 10 requests per minute

Webhooks​

Subscribe to real-time events:

{
  "url": "https://your-app.com/webhooks/aida",
  "events": ["device.status.changed", "energy.threshold.exceeded"],
  "secret": "your_webhook_secret"
}

SDKs and Libraries​

Official SDKs​

  • JavaScript/TypeScript: npm install @aida-platform/sdk
  • Python: pip install aida-platform-sdk
  • React: npm install @aida-platform/react-components

Community Libraries​

  • Vue.js: npm install aida-platform-vue
  • Angular: npm install @aida-platform/angular
  • Flutter: pub add aida_platform_sdk

Support​

  • 📚 Documentation: Comprehensive guides and examples
  • 💬 Community: Join our Discord for API discussions
  • 🐛 Issues: Report bugs on GitHub
  • 📧 Support: Enterprise API support available

Next Steps​

Ready to integrate? Start with our Authentication Guide or explore the Device API to control your smart building devices.