🏗️ Aething API

Simplified External API for Construction AI Assistant

Production Ready v1.0.0

📋 API Overview

The Aething API provides a simplified interface for managing users and projects in the Construction AI Assistant platform. This API is designed for paid users who need programmatic access to core functionality.

🔐 Secure Authentication

API key-based authentication with granular permissions and rate limiting

👥 User Management

Create and retrieve users with simplified data models

📁 Project Management

Manage construction projects with essential metadata

🔑 API Key Generation

Generate API keys with specific permissions and expiration

🔐 Authentication

All API requests require authentication using an API key in the request header.

⚠️ Security Requirements

  • API keys must be at least 32 characters long
  • Keys must be in hexadecimal format
  • Rate limiting is enforced per endpoint
  • IP-based blocking for suspicious activity
GET /api/v1/simplified/health
Check API health and version information. No authentication required.

Response Example:

{ "status": "healthy", "timestamp": "2025-08-02T17:30:00", "version": "1.0.0", "features": [ "simplified-user-management", "simplified-project-management", "api-key-generation", "rate-limiting", "security-monitoring" ] }

👥 User Management

POST /api/v1/simplified/users
Create a new user in the system. Requires users:create permission.

Request Parameters:

email string (email) Required
username string (3-20 chars, alphanumeric) Required
first_name string Required
last_name string Required
company_id integer Required
role string (default: "user") Optional

Response Example:

{ "id": 123, "email": "john.doe@company.com", "username": "johndoe", "first_name": "John", "last_name": "Doe", "company_id": 1, "role": "user", "created_at": "2025-08-02T17:30:00" }
GET /api/v1/simplified/users/{user_id}
Retrieve user information by ID. Requires users:read permission.

Path Parameters:

user_id integer Required

Response Example:

{ "id": 123, "email": "john.doe@company.com", "username": "johndoe", "first_name": "John", "last_name": "Doe", "company_id": 1, "role": "user", "created_at": "2025-08-02T17:30:00" }

📁 Project Management

POST /api/v1/simplified/projects
Create a new project. Requires projects:create permission.

Request Parameters:

name string (min 2 chars) Required
description string Optional
company_id integer Required

Response Example:

{ "id": 456, "name": "Downtown Office Complex", "description": "Modern office building with 20 floors", "company_id": 1, "created_at": "2025-08-02T17:30:00" }
GET /api/v1/simplified/projects/{project_id}
Retrieve project information by ID. Requires projects:read permission.

Path Parameters:

project_id integer Required

Response Example:

{ "id": 456, "name": "Downtown Office Complex", "description": "Modern office building with 20 floors", "company_id": 1, "created_at": "2025-08-02T17:30:00" }

🔑 API Key Management

POST /api/v1/simplified/api-keys/generate
Generate a new API key with specific permissions. Requires api_keys:create permission.

Request Parameters:

permissions array of strings Required
expires_in_days integer (default: 30) Optional

Response Example:

{ "api_key": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12", "expires_at": "2025-09-01T17:30:00", "permissions": ["users:create", "users:read", "projects:create", "projects:read"] }

⚡ Rate Limiting

GET /api/v1/simplified/rate-limits/info
Get information about rate limits for specific endpoints.

Query Parameters:

endpoint string Required

Response Example:

{ "current_usage": 45, "limit": 100, "reset_time": "2025-08-02T18:30:00", "endpoint": "users" }

📊 Rate Limit Details

  • Users endpoints: 100 requests per hour
  • Projects endpoints: 50 requests per hour
  • API Keys endpoints: 10 requests per hour
  • IP blocking: Automatic blocking for suspicious activity

⚠️ Error Handling

Error Codes
Examples

Common HTTP Status Codes:

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

Error Response Example:

{ "detail": "Insufficient permissions: users:create required" }

🔒 Security Analysis

🔑 API Key Security

  • 32+ character hexadecimal format
  • Automatic expiration
  • Granular permissions
  • Secure storage in database

🛡️ Rate Limiting

  • Per-endpoint limits
  • IP-based monitoring
  • Automatic blocking
  • Configurable thresholds

🚨 Threat Detection

  • Suspicious activity monitoring
  • IP address blocking
  • Request pattern analysis
  • Real-time alerts

📊 Audit Logging

  • All requests logged
  • IP address tracking
  • User agent monitoring
  • Security event alerts

🎯 Security Recommendations for Paid Users

  1. Rotate API keys regularly - Generate new keys every 30-90 days
  2. Use minimal permissions - Only grant necessary access
  3. Monitor usage patterns - Set up alerts for unusual activity
  4. Secure key storage - Use environment variables or secure vaults
  5. Implement retry logic - Handle rate limiting gracefully
  6. Validate responses - Always verify API responses

© 2025 Aething Construction AI Assistant. All rights reserved.

API Version: 1.0.0 | Documentation updated: August 2, 2025