openapi: "3.0.3"
info:
  title: LotusCloud API
  description: |
    LotusCloud — Vietnamese Enterprise Cloud Services API.
    All endpoints require JWT authentication via `Authorization: Bearer <token>` and
    tenant isolation via `X-Project-ID` header (except auth endpoints).
  version: "1.0.0"
  contact:
    name: LotusCloud Team
    url: https://lotuscloud.vn
  license:
    name: Proprietary

servers:
  - url: http://localhost:8080
    description: Local development (API Gateway)
  - url: https://api.lotuscloud.vn
    description: Production

tags:
  - name: Auth
    description: Authentication (register, login, refresh, logout)
  - name: IAM
    description: Identity & Access Management (users, projects, roles, MFA, API-keys)
  - name: Compute
    description: Virtual Machines lifecycle
  - name: Storage
    description: Object Storage (buckets & objects)
  - name: Network
    description: Virtual Private Clouds & Security Groups
  - name: SQL
    description: Managed SQL Databases
  - name: Billing
    description: Usage, invoices, cost breakdown
  - name: Load Balancer
    description: Layer-4/7 load balancers
  - name: DNS
    description: DNS zones & records
  - name: Key Vault
    description: Secrets, keys & certificates
  - name: Container
    description: Managed Kubernetes clusters
  - name: Monitor
    description: Activity logs, metrics & alerts
  - name: Resource Manager
    description: Resource groups, tags & quotas
  - name: Registry
    description: Container image registry
  - name: App Service
    description: PaaS web app hosting
  - name: VPN Gateway
    description: Site-to-site VPN connections
  - name: Firewall
    description: Network firewall & WAF policies
  - name: Backup
    description: Backup vaults, policies & jobs
  - name: Serverless
    description: Function Apps, invocations & triggers
  - name: CDN
    description: Content Delivery Network profiles & endpoints
  - name: Cache
    description: Managed Redis Cache instances
  - name: API Management
    description: API products, endpoints & subscriptions
  - name: Event Grid
    description: Event topics, subscriptions & publishing
  - name: Cost Management
    description: Budgets, anomalies & cost reports
  - name: Policy
    description: Policy definitions, assignments & compliance

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    ProjectID:
      name: X-Project-ID
      in: header
      required: true
      schema:
        type: string
        format: uuid
      description: Tenant project ID for resource isolation
    ResourceID:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    SuccessEnvelope:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
        meta:
          type: object
    ErrorEnvelope:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}

security:
  - bearerAuth: []

paths:
  # ── Auth ────────────────────────────────────────────────
  /api/v1/auth/register:
    post:
      tags: [Auth]
      summary: Register a new user
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, full_name]
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
                full_name: { type: string }
      responses:
        "201": { description: User created }
        "400": { description: Validation error }

  /api/v1/auth/login:
    post:
      tags: [Auth]
      summary: Authenticate and receive JWT
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string }
      responses:
        "200":
          description: JWT access token
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      access_token: { type: string }
                      refresh_token: { type: string }

  /api/v1/auth/refresh:
    post:
      tags: [Auth]
      summary: Refresh access token
      security: []
      responses:
        "200": { description: New access token }

  /api/v1/auth/logout:
    post:
      tags: [Auth]
      summary: Revoke refresh token
      responses:
        "200": { description: Logged out }

  # ── IAM ─────────────────────────────────────────────────
  /api/v1/users/me:
    get:
      tags: [IAM]
      summary: Get current user profile
      responses:
        "200": { description: User profile }

  /api/v1/projects:
    get:
      tags: [IAM]
      summary: List projects
      responses:
        "200": { description: List of projects }
    post:
      tags: [IAM]
      summary: Create a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
      responses:
        "201": { description: Project created }

  # ── Compute ─────────────────────────────────────────────
  /api/v1/instances:
    get:
      tags: [Compute]
      summary: List virtual machines
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of VMs }
    post:
      tags: [Compute]
      summary: Create a virtual machine
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, flavor, region]
              properties:
                name: { type: string }
                flavor: { type: string }
                region: { type: string }
                image: { type: string }
      responses:
        "201": { description: VM created }

  /api/v1/instances/{id}:
    get:
      tags: [Compute]
      summary: Get VM details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: VM details }
    delete:
      tags: [Compute]
      summary: Delete a VM
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/instances/{id}/start:
    post:
      tags: [Compute]
      summary: Start a VM
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: VM started }

  /api/v1/instances/{id}/stop:
    post:
      tags: [Compute]
      summary: Stop a VM
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: VM stopped }

  # ── Storage ─────────────────────────────────────────────
  /api/v1/buckets:
    get:
      tags: [Storage]
      summary: List storage buckets
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of buckets }
    post:
      tags: [Storage]
      summary: Create a bucket
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, region]
              properties:
                name: { type: string }
                region: { type: string }
      responses:
        "201": { description: Bucket created }

  /api/v1/buckets/{name}:
    delete:
      tags: [Storage]
      summary: Delete a bucket
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - name: name
          in: path
          required: true
          schema: { type: string }
      responses:
        "204": { description: Deleted }

  # ── Network ─────────────────────────────────────────────
  /api/v1/vpcs:
    get:
      tags: [Network]
      summary: List VPCs
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of VPCs }
    post:
      tags: [Network]
      summary: Create a VPC
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: VPC created }

  # ── SQL ─────────────────────────────────────────────────
  /api/v1/databases:
    get:
      tags: [SQL]
      summary: List managed databases
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of databases }
    post:
      tags: [SQL]
      summary: Create a managed database
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Database created }

  # ── Billing ─────────────────────────────────────────────
  /api/v1/billing/usage:
    get:
      tags: [Billing]
      summary: Get usage report
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: Usage data }

  /api/v1/billing/invoices:
    get:
      tags: [Billing]
      summary: List invoices
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of invoices }

  # ── Load Balancer ───────────────────────────────────────
  /api/v1/load-balancers:
    get:
      tags: [Load Balancer]
      summary: List load balancers
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of LBs }
    post:
      tags: [Load Balancer]
      summary: Create a load balancer
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: LB created }

  # ── DNS ─────────────────────────────────────────────────
  /api/v1/zones:
    get:
      tags: [DNS]
      summary: List DNS zones
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of zones }
    post:
      tags: [DNS]
      summary: Create a DNS zone
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Zone created }

  # ── Key Vault ───────────────────────────────────────────
  /api/v1/vaults:
    get:
      tags: [Key Vault]
      summary: List key vaults
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of vaults }
    post:
      tags: [Key Vault]
      summary: Create a key vault
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Vault created }

  # ── Container ───────────────────────────────────────────
  /api/v1/clusters:
    get:
      tags: [Container]
      summary: List Kubernetes clusters
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of clusters }
    post:
      tags: [Container]
      summary: Create a Kubernetes cluster
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Cluster created }

  # ── Monitor ─────────────────────────────────────────────
  /api/v1/activity-logs:
    get:
      tags: [Monitor]
      summary: List activity logs
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: Activity log entries }

  /api/v1/metric-rules:
    get:
      tags: [Monitor]
      summary: List metric alert rules
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of metric rules }

  # ── Resource Manager ────────────────────────────────────
  /api/v1/resource-groups:
    get:
      tags: [Resource Manager]
      summary: List resource groups
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of resource groups }
    post:
      tags: [Resource Manager]
      summary: Create a resource group
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Resource group created }

  # ── Registry ────────────────────────────────────────────
  /api/v1/registries:
    get:
      tags: [Registry]
      summary: List container registries
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of registries }
    post:
      tags: [Registry]
      summary: Create a container registry
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Registry created }

  # ── App Service ─────────────────────────────────────────
  /api/v1/webapps:
    get:
      tags: [App Service]
      summary: List web apps
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of web apps }
    post:
      tags: [App Service]
      summary: Create a web app
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Web app created }

  # ── VPN Gateway ─────────────────────────────────────────
  /api/v1/vpn-gateways:
    get:
      tags: [VPN Gateway]
      summary: List VPN gateways
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of VPN gateways }
    post:
      tags: [VPN Gateway]
      summary: Create a VPN gateway
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: VPN gateway created }

  # ── Firewall ────────────────────────────────────────────
  /api/v1/firewalls:
    get:
      tags: [Firewall]
      summary: List firewalls
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of firewalls }
    post:
      tags: [Firewall]
      summary: Create a firewall
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Firewall created }

  # ── Backup ──────────────────────────────────────────────
  /api/v1/backup-vaults:
    get:
      tags: [Backup]
      summary: List backup vaults
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of backup vaults }
    post:
      tags: [Backup]
      summary: Create a backup vault
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "201": { description: Backup vault created }

  # ── Serverless / Functions ──────────────────────────────
  /api/v1/functions:
    get:
      tags: [Serverless]
      summary: List function apps
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of functions }
    post:
      tags: [Serverless]
      summary: Create a function app
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, runtime, region]
              properties:
                name: { type: string }
                runtime: { type: string, enum: [nodejs20, python3.12, go1.22, java21] }
                region: { type: string }
                memory_mb: { type: integer, default: 128 }
                timeout_sec: { type: integer, default: 30 }
      responses:
        "201": { description: Function created }

  /api/v1/functions/{id}:
    get:
      tags: [Serverless]
      summary: Get function details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Function details }
    put:
      tags: [Serverless]
      summary: Update a function
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Function updated }
    delete:
      tags: [Serverless]
      summary: Delete a function
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/functions/{id}/invoke:
    post:
      tags: [Serverless]
      summary: Invoke a function
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payload: { type: object }
      responses:
        "200": { description: Invocation result }

  /api/v1/functions/{id}/triggers:
    get:
      tags: [Serverless]
      summary: List function triggers
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: List of triggers }
    post:
      tags: [Serverless]
      summary: Create a function trigger
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "201": { description: Trigger created }

  # ── CDN ─────────────────────────────────────────────────
  /api/v1/cdn-profiles:
    get:
      tags: [CDN]
      summary: List CDN profiles
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of CDN profiles }
    post:
      tags: [CDN]
      summary: Create a CDN profile
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                sku: { type: string, enum: [Standard, Premium], default: Standard }
      responses:
        "201": { description: CDN profile created }

  /api/v1/cdn-profiles/{id}:
    get:
      tags: [CDN]
      summary: Get CDN profile details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: CDN profile details }
    delete:
      tags: [CDN]
      summary: Delete a CDN profile
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/cdn-profiles/{id}/endpoints:
    get:
      tags: [CDN]
      summary: List CDN endpoints
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: List of CDN endpoints }
    post:
      tags: [CDN]
      summary: Create a CDN endpoint
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "201": { description: CDN endpoint created }

  # ── Cache ───────────────────────────────────────────────
  /api/v1/cache-instances:
    get:
      tags: [Cache]
      summary: List cache instances
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of cache instances }
    post:
      tags: [Cache]
      summary: Create a cache instance
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, region]
              properties:
                name: { type: string }
                sku: { type: string, enum: [Basic, Standard, Premium], default: Basic }
                region: { type: string }
                capacity_gb: { type: number, default: 1 }
      responses:
        "201": { description: Cache instance created }

  /api/v1/cache-instances/{id}:
    get:
      tags: [Cache]
      summary: Get cache instance details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Cache instance details }
    delete:
      tags: [Cache]
      summary: Delete a cache instance
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/cache-instances/{id}/scale:
    post:
      tags: [Cache]
      summary: Scale a cache instance
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sku: { type: string }
                capacity_gb: { type: number }
      responses:
        "200": { description: Cache instance scaled }

  # ── API Management ──────────────────────────────────────
  /api/v1/api-products:
    get:
      tags: [API Management]
      summary: List API products
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of API products }
    post:
      tags: [API Management]
      summary: Create an API product
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                description: { type: string }
                version: { type: string, default: v1 }
      responses:
        "201": { description: API product created }

  /api/v1/api-products/{id}:
    get:
      tags: [API Management]
      summary: Get API product details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: API product details }
    delete:
      tags: [API Management]
      summary: Delete an API product
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/api-products/{id}/subscriptions:
    get:
      tags: [API Management]
      summary: List API subscriptions
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: List of subscriptions }
    post:
      tags: [API Management]
      summary: Create API subscription (generates API key)
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [app_name]
              properties:
                app_name: { type: string }
                quota: { type: integer, default: 10000 }
      responses:
        "201": { description: Subscription created with API key }

  # ── Event Grid ──────────────────────────────────────────
  /api/v1/topics:
    get:
      tags: [Event Grid]
      summary: List event topics
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of topics }
    post:
      tags: [Event Grid]
      summary: Create an event topic
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
      responses:
        "201": { description: Topic created }

  /api/v1/topics/{id}:
    get:
      tags: [Event Grid]
      summary: Get topic details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Topic details }
    delete:
      tags: [Event Grid]
      summary: Delete a topic
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/topics/{id}/publish:
    post:
      tags: [Event Grid]
      summary: Publish an event to a topic
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [event_type, subject, data]
              properties:
                event_type: { type: string }
                subject: { type: string }
                data: { type: object }
      responses:
        "201": { description: Event published }

  /api/v1/topics/{id}/subscriptions:
    get:
      tags: [Event Grid]
      summary: List topic subscriptions
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: List of subscriptions }
    post:
      tags: [Event Grid]
      summary: Create a topic subscription
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [webhook_url, event_types]
              properties:
                webhook_url: { type: string, format: uri }
                event_types: { type: string }
                max_retries: { type: integer, default: 3 }
      responses:
        "201": { description: Subscription created }

  # ── Cost Management ─────────────────────────────────────
  /api/v1/budgets:
    get:
      tags: [Cost Management]
      summary: List budgets
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of budgets }
    post:
      tags: [Cost Management]
      summary: Create a budget
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, amount]
              properties:
                name: { type: string }
                amount: { type: number }
                currency: { type: string, default: VND }
                period: { type: string, enum: [monthly, quarterly, yearly], default: monthly }
                alert_threshold: { type: number, default: 80 }
      responses:
        "201": { description: Budget created }

  /api/v1/budgets/{id}:
    get:
      tags: [Cost Management]
      summary: Get budget details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Budget details }
    put:
      tags: [Cost Management]
      summary: Update a budget
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Budget updated }
    delete:
      tags: [Cost Management]
      summary: Delete a budget
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/anomalies:
    get:
      tags: [Cost Management]
      summary: List cost anomalies
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of anomalies }

  /api/v1/anomalies/detect:
    post:
      tags: [Cost Management]
      summary: Report a cost anomaly
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [resource_type, expected_cost, actual_cost]
              properties:
                resource_type: { type: string }
                resource_id: { type: string }
                expected_cost: { type: number }
                actual_cost: { type: number }
      responses:
        "201": { description: Anomaly detected and recorded }

  /api/v1/anomalies/{id}/acknowledge:
    post:
      tags: [Cost Management]
      summary: Acknowledge a cost anomaly
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Anomaly acknowledged }

  /api/v1/reports:
    get:
      tags: [Cost Management]
      summary: List cost reports
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of reports }
    post:
      tags: [Cost Management]
      summary: Generate a cost report
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, period]
              properties:
                name: { type: string }
                period: { type: string, enum: [daily, weekly, monthly] }
      responses:
        "201": { description: Report generation started }

  # ── Policy & Governance ─────────────────────────────────
  /api/v1/policies:
    get:
      tags: [Policy]
      summary: List policies
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of policies }
    post:
      tags: [Policy]
      summary: Create a policy
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                description: { type: string }
                type: { type: string, enum: [builtin, custom], default: custom }
                category: { type: string, enum: [security, cost, compliance, naming] }
                enforcement_mode: { type: string, enum: [audit, deny, disabled], default: audit }
                severity: { type: string, enum: [low, medium, high, critical], default: medium }
                definition: { type: string, description: JSON policy rules }
      responses:
        "201": { description: Policy created }

  /api/v1/policies/{id}:
    get:
      tags: [Policy]
      summary: Get policy details
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Policy details }
    put:
      tags: [Policy]
      summary: Update a policy
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200": { description: Policy updated }
    delete:
      tags: [Policy]
      summary: Delete a policy
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "204": { description: Deleted }

  /api/v1/assignments:
    get:
      tags: [Policy]
      summary: List policy assignments
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of assignments }
    post:
      tags: [Policy]
      summary: Create a policy assignment
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [policy_id, scope]
              properties:
                policy_id: { type: string, format: uuid }
                scope: { type: string, enum: [project, resource-group, resource] }
                scope_id: { type: string }
                parameters: { type: string, description: JSON parameters override }
      responses:
        "201": { description: Assignment created }

  /api/v1/compliance:
    get:
      tags: [Policy]
      summary: List compliance results
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      responses:
        "200": { description: List of compliance results }

  /api/v1/compliance/evaluate:
    post:
      tags: [Policy]
      summary: Evaluate compliance for a resource
      parameters:
        - $ref: "#/components/parameters/ProjectID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [policy_id, resource_type, resource_id]
              properties:
                policy_id: { type: string, format: uuid }
                resource_type: { type: string }
                resource_id: { type: string }
      responses:
        "201": { description: Compliance evaluation result }

  /api/v1/compliance/policy/{policyId}:
    get:
      tags: [Policy]
      summary: List compliance results for a specific policy
      parameters:
        - $ref: "#/components/parameters/ProjectID"
        - name: policyId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: Compliance results for policy }