{
    "openapi": "3.1.0",
    "info": {
        "title": "Công ty thiết kế thi công nội thất đẹp [AVALO] API Gateway",
        "version": "2026.1.0",
        "description": "Official API Gateway, Architectural Knowledge Engine, and Sandbox for Autonomous AI Agents and Developers.",
        "contact": {
            "name": "AVALO Technical Support Desk",
            "email": "avalo@avalo.vn",
            "url": "https://avalo.vn/contact"
        },
        "license": {
            "name": "Proprietary - AVALO Interior Design",
            "url": "https://avalo.vn/privacy"
        },
        "x-sandbox": {
            "endpoint": "https://avalo.vn/api/v1/sandbox",
            "free_tier": true,
            "rate_limit": "120 requests/minute",
            "demo_key": "demo_sandbox_key",
            "docs": "https://avalo.vn/docs/sandbox"
        }
    },
    "servers": [
        {
            "url": "https://avalo.vn",
            "description": "Production Gateway (HTTP/2 / HTTP/3)"
        }
    ],
    "components": {
        "securitySchemes": {
            "FreeTierAuth": {
                "type": "apiKey",
                "name": "X-API-Key",
                "in": "header",
                "description": "Instant free tier access. Use demo key demo_sandbox_key or call public endpoints without credentials in sandbox mode."
            }
        },
        "schemas": {
            "ProblemDetails": {
                "type": "object",
                "description": "RFC 9457 Standardized Problem Details for HTTP APIs",
                "properties": {
                    "type": {
                        "type": "string",
                        "format": "uri"
                    },
                    "title": {
                        "type": "string"
                    },
                    "status": {
                        "type": "integer"
                    },
                    "code": {
                        "type": "string"
                    },
                    "detail": {
                        "type": "string"
                    },
                    "hint": {
                        "type": "string"
                    }
                },
                "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                ]
            },
            "HomepageResponse": {
                "type": "object",
                "description": "Structured representation of AVALO homepage",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Công ty thiết kế thi công nội thất đẹp [AVALO]"
                    },
                    "address": {
                        "type": "string"
                    },
                    "hotline": {
                        "type": "string"
                    },
                    "core_services": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "featured_portfolio": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    }
                }
            },
            "DocsResponse": {
                "type": "object",
                "description": "Developer and AI agent documentation payload",
                "properties": {
                    "title": {
                        "type": "string"
                    },
                    "version": {
                        "type": "string"
                    },
                    "endpoints": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            },
            "TrustPageResponse": {
                "type": "object",
                "description": "Standard trust anchor page payload (About, Contact, Privacy)",
                "properties": {
                    "title": {
                        "type": "string"
                    },
                    "canonical_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "content": {
                        "type": "string"
                    },
                    "last_modified": {
                        "type": "string"
                    }
                },
                "required": [
                    "title",
                    "canonical_url",
                    "content"
                ]
            },
            "HealthResponse": {
                "type": "object",
                "description": "System health telemetry and uptime statistics",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "operational"
                    },
                    "system": {
                        "type": "string"
                    },
                    "version": {
                        "type": "string"
                    },
                    "timestamp": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "rate_limit": {
                        "type": "object"
                    }
                },
                "required": [
                    "status",
                    "system",
                    "version",
                    "timestamp"
                ]
            },
            "SandboxSimulationInput": {
                "type": "object",
                "description": "Input parameters for interior design estimation simulation in sandbox",
                "properties": {
                    "property_type": {
                        "type": "string",
                        "enum": [
                            "villa",
                            "apartment",
                            "townhouse",
                            "penthouse"
                        ],
                        "example": "villa"
                    },
                    "area_m2": {
                        "type": "number",
                        "example": 250
                    },
                    "style": {
                        "type": "string",
                        "enum": [
                            "modern_luxury",
                            "contemporary",
                            "neoclassical",
                            "indochine"
                        ],
                        "example": "modern_luxury"
                    }
                },
                "required": [
                    "property_type",
                    "area_m2"
                ]
            },
            "SandboxSimulationResponse": {
                "type": "object",
                "description": "Instant estimation result from sandbox environment",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": true
                    },
                    "simulation_mode": {
                        "type": "string",
                        "example": "sandbox_free_tier"
                    },
                    "project_summary": {
                        "type": "object"
                    },
                    "estimated_cost_range_vnd": {
                        "type": "object"
                    },
                    "milestones": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    },
    "paths": {
        "/": {
            "get": {
                "operationId": "getHomepage",
                "summary": "Homepage & Publication Overview",
                "description": "Retrieve core corporate positioning, architectural capabilities, and design feed. Supports RFC 9110 text/html and text/markdown.",
                "responses": {
                    "200": {
                        "description": "Successful homepage retrieval",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HomepageResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/docs": {
            "get": {
                "operationId": "getDeveloperDocs",
                "summary": "Developer Documentation & Agent Guidelines",
                "description": "Complete developer guidelines, system architecture, sandbox access, and integration protocols.",
                "responses": {
                    "200": {
                        "description": "Developer documentation payload",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DocsResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/docs/sandbox": {
            "get": {
                "operationId": "getSandboxGuide",
                "summary": "Free Tier & Sandbox Environment Guide",
                "description": "Instructions for testing AVALO API endpoints in sandbox mode without human onboarding friction.",
                "responses": {
                    "200": {
                        "description": "Sandbox documentation markdown",
                        "content": {
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/about": {
            "get": {
                "operationId": "getAboutCompany",
                "summary": "Company Mission, Architects & Standards",
                "description": "Retrieve company background, verified architectural competencies, and organizational governance.",
                "responses": {
                    "200": {
                        "description": "Trust Anchor: About Information",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TrustPageResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/contact": {
            "get": {
                "operationId": "getContactChannels",
                "summary": "Official Business Channels & Office Details",
                "description": "Official verified communication channels, office address, and support hotline.",
                "responses": {
                    "200": {
                        "description": "Trust Anchor: Contact Channels",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TrustPageResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/privacy": {
            "get": {
                "operationId": "getPrivacyPolicy",
                "summary": "Privacy Policy & Customer Data Protection",
                "description": "Data privacy guarantees compliant with Decree 13/2023/ND-CP and international standards.",
                "responses": {
                    "200": {
                        "description": "Trust Anchor: Privacy Statement",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TrustPageResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/llms.txt": {
            "get": {
                "operationId": "getAgentInstructions",
                "summary": "Agent Instructions & When-to-Use Guide",
                "description": "Canonical llms.txt guide detailing operational boundaries, best-fit use cases, and resources.",
                "responses": {
                    "200": {
                        "description": "llms.txt Manifest",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/llms-full.txt": {
            "get": {
                "operationId": "getFullKnowledgeCorpus",
                "summary": "Full Knowledge Base & Architectural Portfolio for RAG",
                "description": "Comprehensive text corpus of all research articles, portfolio transcripts, and technical playbooks.",
                "responses": {
                    "200": {
                        "description": "Complete text corpus",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/health": {
            "get": {
                "operationId": "getSystemHealth",
                "summary": "System Health & Latency Telemetry",
                "description": "Real-time uptime status, environment telemetry, and SLA guarantees.",
                "responses": {
                    "200": {
                        "description": "System operational status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HealthResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/sandbox": {
            "get": {
                "operationId": "getDesignSandboxStatus",
                "summary": "Retrieve Sandbox Status & Sample Schemas",
                "description": "Returns instant sandbox status, sample parameters, and free-tier capabilities without registration.",
                "responses": {
                    "200": {
                        "description": "Sandbox telemetry status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SandboxSimulationResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "runDesignSandboxSimulation",
                "summary": "Run Instant Interior Design Simulation in Sandbox",
                "description": "Submits project parameters (area, property type, style) and receives immediate cost estimation and material blueprint in sandbox mode.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SandboxSimulationInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Simulation completed successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SandboxSimulationResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request or malformed parameters",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Resource or endpoint not found",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 req/min)",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProblemDetails"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}