API Reference
Relevant source files
The following files were used as context for generating this wiki page:The DevSkyy API is a high-performance interface built with FastAPI that serves as the primary gateway to the platform's 54 AI agents and enterprise automation capabilities. It provides a RESTful, versioned, and secure set of endpoints for managing everything from e-commerce operations and marketing campaigns to code generation and system monitoring. The API is designed for enterprise-grade deployment, featuring robust authentication, detailed monitoring, and automated documentation.
The API currently exposes 47 production-ready endpoints, with over 30 additional endpoints planned to provide full coverage for all agent functionalities. The system uses Pydantic for strict data validation and automatically generates OpenAPI (Swagger) documentation for all available endpoints. For more details on the implementation plan, see the Implementation Roadmap.
Sources: QUICK_REFERENCE.md, LUXURY_FASHION_AUTOMATION.md, ai_orchestration/API_REQUIREMENTS.md
API Architecture
The API is built on the FastAPI framework, leveraging its asynchronous capabilities for high performance. The entry point is main.py, which initializes the application and includes modular routers for different domains of functionality. This modular design promotes separation of concerns and scalability.
Sources: main.py, TRANSFORMERS_INTEGRATION_ANALYSIS.md
Request Flow
The following diagram illustrates the typical flow of a request through the API to an underlying agent.
This diagram shows a client request being processed by FastAPI, routed, authenticated, validated, and finally handled by the orchestration engine and relevant AI agents before a response is returned.
Sources: LUXURY_FASHION_AUTOMATION.md, IMPLEMENTATION_ROADMAP.md
API Versioning
The API is versioned to ensure backward compatibility and allow for future evolution. All current production endpoints are prefixed with /api/v1/. A future migration to /api/v2/ is planned, and the system will include middleware to handle deprecation headers (Deprecation, Sunset).
Sources: IMPLEMENTATION_ROADMAP.md, QUICK_REFERENCE.md
Authentication & Security
The platform is transitioning from a simple API key system to a robust, enterprise-grade security model based on JWT and OAuth2, compliant with RFC 7519.
Sources: IMPLEMENTATION_ROADMAP.md, PRODUCTION_CHECKLIST.md
Authentication Flow
Authentication is handled via JWT bearer tokens, with a standard flow for login, token refresh, and access to protected resources.
This sequence diagram illustrates the user login process to obtain JWTs and the subsequent use of the access token to access a protected endpoint.
Sources: IMPLEMENTATION_ROADMAP.md, IMPLEMENTATION_GUIDE.md, UNICORN_QUICK_START_CHECKLIST.md
Role-Based Access Control (RBAC)
Access to endpoints is controlled by a 5-tier RBAC system. The role is encoded within the JWT payload and checked by a dependency for protected routes.
| Role | Description |
|---|---|
SUPER_ADMIN | Full access to all system functionalities, including configuration. |
ADMIN | Access to business operations like finance and user management. |
DEVELOPER | Access to code generation, deployment, and system agents. |
API_USER | Standard access for external integrations, limited to non-admin tasks. |
READ_ONLY | Access to view dashboards, metrics, and reports. |
Sources: PRODUCTION_CHECKLIST.md, IMPLEMENTATION_GUIDE.md
API Endpoints
The API is organized into several routers, each handling a specific domain. The following tables summarize the key endpoints defined and planned for the system.
Critical Endpoints (Must Implement)
These endpoints are essential for the core functionality of the orchestration system.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/orchestration/health | Get the overall health of the orchestration system and its partnerships. |
GET | /api/v1/orchestration/metrics | Get real-time performance metrics for all partnerships. |
POST | /api/v1/orchestration/decisions | Submits context to the strategic decision engine for recommendations. |
GET | /api/v1/partnerships/ | Get the status of all active partnerships. |
PUT | /api/v1/partnerships/{id}/deliverables/{id} | Update the progress of a specific deliverable within a partnership. |
Sources: ai_orchestration/API_REQUIREMENTS.md
Luxury Fashion Automation Endpoints
These endpoints control the advanced automation workflows for luxury fashion brands.
| Method | Path | Description |
|---|---|---|
POST | /api/v1/luxury-automation/visual-content/generate | Generate a single visual asset (e.g., product photo). |
POST | /api/v1/luxury-automation/finance/inventory/sync | Synchronize inventory levels from an e-commerce channel. |
POST | /api/v1/luxury-automation/marketing/campaigns/create | Create a new multi-channel marketing campaign with A/B testing variants. |
POST | /api/v1/luxury-automation/code/generate | Generate code snippets based on a natural language description. |
POST | /api/v1/luxury-automation/workflows/create | Create a complex, multi-agent workflow like a full brand launch. |
POST | /api/v1/luxury-automation/workflows/{id}/execute | Execute a previously created workflow. |
GET | /api/v1/luxury-automation/system/status | Get the complete status of the luxury automation system. |
Sources: LUXURY_FASHION_AUTOMATION.md
Missing Endpoints
A significant number of agents do not yet have corresponding API endpoints. Full implementation is planned.
Areas with missing endpoints:
- Social Media Automation (Facebook, Instagram)
- Email/SMS Marketing Campaigns
- Customer Service (Ticketing, Chatbots)
- Voice and Audio Content Generation
- Blockchain and NFT Asset Management
- Brand Intelligence and Competitive Analysis
Sources: QUICK_REFERENCE.md, IMPLEMENTATION_ROADMAP.md
Data Models & Validation
All API inputs and outputs are strictly validated using Pydantic models. This ensures data integrity, provides clear error messages for invalid requests, and powers the automatic generation of OpenAPI documentation.
Example Request Model
This Pydantic model is used for validating requests to the visual content generation endpoint.
# From: LUXURY_FASHION_AUTOMATION.md
request = {
"prompt": "luxury handbag on marble surface, studio lighting, high-end fashion photography",
"content_type": "product_photo",
"style_preset": "minimalist_luxury",
"width": 1024,
"height": 1024,
"quality": "high",
"variations": 3
}
Sources: LUXURY_FASHION_AUTOMATION.md
Error Handling
The system features a sophisticated error handling mechanism, including a custom exception hierarchy and a persistent Error Ledger System.
- Custom Exceptions: Over 50 specific exception classes are defined in
core/exceptions.pyto provide granular error details. These are automatically mapped to appropriate HTTP status codes. - Error Ledger: All errors are tracked and persisted to a JSON file (
/artifacts/error-ledger-<run_id>.json). This ledger categorizes errors by type (e.g., Authentication, Database, Agent) and severity, and includes full stack traces for debugging.
Sources: PRODUCTION_CHECKLIST.md
Monitoring and Health
The API includes dedicated endpoints for monitoring system health and performance, designed for integration with tools like Prometheus and Grafana.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/health | A basic health check endpoint. |
GET | /api/v1/health/detailed | A comprehensive health check including database and Redis connectivity. |
GET | /api/v1/metrics | Exposes performance metrics in a Prometheus-compatible format. |
Sources: UNICORN_QUICK_START_CHECKLIST.md, PRODUCTION_CHECKLIST.md
API Documentation Generation
The project uses FastAPI's built-in capabilities to automatically generate interactive API documentation (Swagger UI and ReDoc) from the code, Pydantic models, and docstrings. A script is also available to generate a static openapi.json file.
The documentation is available at the /docs and /redoc endpoints of the running application.
Sources: LUXURY_FASHION_AUTOMATION.md, scripts/generate_openapi.py
Summary
The DevSkyy API is the central nervous system of the platform, providing structured, secure, and performant access to its powerful AI automation features. While a solid foundation of 47 endpoints is in place, the roadmap includes significant expansion to cover all 54 agents. The architecture prioritizes enterprise requirements such as versioning, robust security (JWT/RBAC), detailed monitoring, and comprehensive error tracking, making it a scalable and reliable interface for both internal and external developers.