{
  "openapi": "3.0.3",
  "info": {
    "title": "Synlake API",
    "description": "B2AI infrastructure API for autonomous agents. Normalizes AWS, GCP, and Azure into a unified schema, generates execution kits (Terraform + CLI), and simulates costs before deployment.",
    "version": "0.1.0",
    "contact": {
      "name": "Synlake",
      "url": "https://synlake.ai",
      "email": "contactcharly00@gmail.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.synlake.ai/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/register": {
      "post": {
        "operationId": "registerAgent",
        "summary": "Register a new agent",
        "description": "Creates a new API key for an agent. Returns the key once — it cannot be retrieved again. Same email deactivates the old key and generates a new one.",
        "security": [],
        "tags": ["Auth"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Agent owner email"
                  },
                  "name": {
                    "type": "string",
                    "description": "Optional agent name"
                  }
                }
              },
              "example": {
                "email": "agent@company.com",
                "name": "My ML Agent"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterResponse"
                },
                "example": {
                  "api_key": "sk_synlake_abc123...",
                  "billing_status": "free",
                  "free_calls_remaining": 100,
                  "spending_cap": 100,
                  "message": "Save this key — it will not be shown again."
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/infrastructure/query": {
      "post": {
        "operationId": "queryInfrastructure",
        "summary": "Query infrastructure with execution kit",
        "description": "The primary endpoint. Describe what you need — Synlake responds with the optimal instance, cross-provider alternatives, Terraform HCL, CLI commands, and cost estimates. Cost: $0.05 (without kit) or $0.10 (with kit).",
        "tags": ["Infrastructure"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              },
              "example": {
                "intent": "compute",
                "requirements": {
                  "vcpus": 4,
                  "memory_gb": 16,
                  "storage_gb": 100,
                  "gpu": false,
                  "region": "us-east-1"
                },
                "constraints": {
                  "max_monthly_budget_usd": 200,
                  "providers": ["aws", "gcp", "azure"]
                },
                "output": {
                  "include_terraform": true,
                  "include_cli": true,
                  "include_alternatives": true,
                  "pricing_model": "on_demand"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Infrastructure recommendation with execution kit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "422": {
            "description": "No matching instances found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/infrastructure/estimate": {
      "post": {
        "operationId": "estimateCost",
        "summary": "Estimate costs without execution kit",
        "description": "Fast cost-only endpoint. Returns the cheapest instance per provider for your requirements. No Terraform or CLI — just pricing. Cost: $0.01/call.",
        "tags": ["Infrastructure"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateRequest"
              },
              "example": {
                "intent": "compute",
                "requirements": {
                  "vcpus": 8,
                  "memory_gb": 32
                },
                "providers": ["aws", "gcp", "azure"],
                "pricing_model": "on_demand"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cost estimates by provider",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstimateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/execution/validate": {
      "post": {
        "operationId": "validateExecution",
        "summary": "Validate an execution kit",
        "description": "Dry-run validation of Terraform or CLI code. Checks security issues (public access, encryption, IAM), estimates costs, and validates against budget limits. Never executes anything. Cost: $0.05/call.",
        "tags": ["Execution"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateRequest"
              },
              "example": {
                "provider": "aws",
                "execution_type": "terraform",
                "code": "resource \"aws_instance\" \"main\" {\n  ami = \"ami-0c55b159cbfafe1f0\"\n  instance_type = \"t3.xlarge\"\n  root_block_device {\n    volume_size = 100\n    encrypted = true\n  }\n}",
                "agent_budget_limit": 150
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/providers": {
      "get": {
        "operationId": "listProviders",
        "summary": "List supported cloud providers",
        "description": "Returns all supported providers, their services, region count, and last pricing update. Free — no cost per call.",
        "tags": ["Catalog"],
        "responses": {
          "200": {
            "description": "List of providers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvidersResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/agent/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "Get agent usage and billing status",
        "description": "Returns the authenticated agent's billing status, remaining free calls, spending cap, and usage stats for the current cycle. Free — no cost per call.",
        "tags": ["Billing"],
        "responses": {
          "200": {
            "description": "Agent usage data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/billing/activate": {
      "post": {
        "operationId": "activateBilling",
        "summary": "Activate metered billing",
        "description": "Creates a Stripe Checkout session to activate pay-per-execution billing. Returns a URL to complete payment setup. After activation, the agent moves from free tier to metered billing.",
        "tags": ["Billing"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "spending_cap": {
                    "type": "number",
                    "default": 100,
                    "description": "Max monthly spend in USD"
                  },
                  "api_key_id": {
                    "type": "string",
                    "description": "Links subscription to existing API key"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Billing activation session created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActivateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check",
        "description": "Returns API health status, module checks, and active endpoints.",
        "tags": ["System"],
        "security": [],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key in format: sk_synlake_..."
      }
    },
    "schemas": {
      "Provider": {
        "type": "string",
        "enum": ["aws", "gcp", "azure"]
      },
      "PricingModel": {
        "type": "string",
        "enum": ["on_demand", "spot", "reserved_1y"]
      },
      "RegisterResponse": {
        "type": "object",
        "properties": {
          "api_key": { "type": "string" },
          "billing_status": { "type": "string", "enum": ["free"] },
          "free_calls_remaining": { "type": "integer" },
          "spending_cap": { "type": "number" },
          "message": { "type": "string" }
        }
      },
      "QueryRequest": {
        "type": "object",
        "required": ["intent", "requirements"],
        "properties": {
          "intent": { "type": "string", "enum": ["compute"], "description": "Only 'compute' in v0.1" },
          "requirements": {
            "type": "object",
            "properties": {
              "vcpus": { "type": "integer", "description": "Minimum vCPUs" },
              "memory_gb": { "type": "number", "description": "Minimum memory in GB" },
              "storage_gb": { "type": "integer", "default": 30 },
              "gpu": { "type": "boolean", "default": false },
              "region": { "type": "string", "description": "e.g. us-east-1, us-central1" },
              "os": { "type": "string", "enum": ["linux"] },
              "architecture": { "type": "string", "enum": ["x86_64", "arm64"] }
            }
          },
          "constraints": {
            "type": "object",
            "additionalProperties": false,
            "description": "Constraint object. Unknown keys → INVALID_REQUIREMENTS; variants of the budget key (max_monthly_budget, monthly_budget_usd, budget, budget_usd) → suggestions pointing at the canonical name. (SYN-53)",
            "properties": {
              "max_monthly_budget_usd": { "type": "number", "minimum": 0, "description": "Maximum monthly spend in USD. /estimate annotates within_budget per estimate + budget_met top-level (returns 200). /query enforces with 400 BUDGET_EXCEEDED." },
              "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } },
              "compliance": { "type": "array", "items": { "type": "string" } },
              "availability": { "type": "string", "enum": ["standard", "high", "critical"] }
            }
          },
          "output": {
            "type": "object",
            "properties": {
              "include_terraform": { "type": "boolean", "default": true },
              "include_cli": { "type": "boolean", "default": true },
              "include_alternatives": { "type": "boolean", "default": true },
              "max_alternatives": { "type": "integer", "default": 3 },
              "pricing_model": { "$ref": "#/components/schemas/PricingModel" }
            }
          }
        }
      },
      "QueryResponse": {
        "type": "object",
        "properties": {
          "request_id": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" },
          "recommendation": { "$ref": "#/components/schemas/RecommendationItem" },
          "alternatives": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/RecommendationItem" }
          },
          "guardrails": { "$ref": "#/components/schemas/Guardrails" }
        }
      },
      "RecommendationItem": {
        "type": "object",
        "properties": {
          "provider": { "$ref": "#/components/schemas/Provider" },
          "service": { "type": "string" },
          "instance_type": { "type": "string" },
          "region": { "type": "string" },
          "specs": {
            "type": "object",
            "properties": {
              "vcpus": { "type": "integer" },
              "memory_gb": { "type": "number" },
              "storage_gb": { "type": "integer" },
              "network_bandwidth": { "type": "string" }
            }
          },
          "pricing": {
            "type": "object",
            "properties": {
              "hourly": { "type": "number" },
              "monthly_estimate": { "type": "number" },
              "currency": { "type": "string" },
              "pricing_model": { "$ref": "#/components/schemas/PricingModel" },
              "last_updated": { "type": "string" }
            }
          },
          "execution_kit": {
            "type": "object",
            "properties": {
              "terraform": { "type": "string", "description": "Terraform HCL ready to apply" },
              "cli": { "type": "string", "description": "CLI command ready to execute" },
              "estimated_deploy_time": { "type": "string" }
            }
          },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
        }
      },
      "Guardrails": {
        "type": "object",
        "properties": {
          "budget_check": { "type": "string", "enum": ["PASS", "FAIL", "NOT_APPLICABLE"] },
          "monthly_estimate_vs_budget": { "type": "string" },
          "compliance_check": { "type": "string", "enum": ["PASS", "FAIL"] },
          "region_available": { "type": "boolean" }
        }
      },
      "EstimateRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["intent", "requirements"],
        "properties": {
          "intent": { "type": "string", "enum": ["compute"], "description": "v0.1: only 'compute'" },
          "requirements": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "vcpus": { "type": "integer" },
              "memory_gb": { "type": "number" },
              "gpu": { "type": "boolean" },
              "region": { "type": "string" },
              "architecture": { "type": "string", "enum": ["x86_64", "arm64"] }
            }
          },
          "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } },
          "pricing_model": { "$ref": "#/components/schemas/PricingModel" },
          "constraints": {
            "type": "object",
            "additionalProperties": false,
            "description": "Optional. /estimate annotates budget_met + within_budget; /query enforces with BUDGET_EXCEEDED. (SYN-53)",
            "properties": {
              "max_monthly_budget_usd": { "type": "number", "minimum": 0 }
            }
          }
        }
      },
      "EstimateResponse": {
        "type": "object",
        "properties": {
          "request_id": { "type": "string" },
          "estimates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "provider": { "$ref": "#/components/schemas/Provider" },
                "instance_type": { "type": "string" },
                "monthly_estimate": { "type": "number" },
                "within_budget": { "type": "boolean", "description": "Present only when constraints.max_monthly_budget_usd was sent. (SYN-53)" }
              }
            }
          },
          "cheapest": { "$ref": "#/components/schemas/Provider" },
          "savings_vs_most_expensive": { "type": "string" },
          "budget_met": { "type": "boolean", "description": "Present only when constraints.max_monthly_budget_usd was sent. True iff at least one estimate fits. (SYN-53)" },
          "budget_requested": { "type": "number", "description": "Echo of the requested budget. Omitted when no budget was sent. (SYN-53)" },
          "execution_kit_available": { "type": "boolean" },
          "get_api_key": { "type": "string", "format": "uri" }
        }
      },
      "ValidateRequest": {
        "type": "object",
        "required": ["provider", "execution_type", "code"],
        "properties": {
          "provider": { "$ref": "#/components/schemas/Provider" },
          "execution_type": { "type": "string", "enum": ["terraform", "cli"] },
          "code": { "type": "string", "description": "Terraform HCL or CLI command to validate" },
          "agent_budget_limit": { "type": "number", "description": "Monthly budget limit in USD" }
        }
      },
      "ValidateResponse": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "estimated_cost": { "type": "number", "nullable": true },
          "budget_status": { "type": "string", "enum": ["WITHIN_LIMIT", "EXCEEDS_LIMIT", "NOT_APPLICABLE"] },
          "warnings": { "type": "array", "items": { "type": "string" } },
          "security_checks": {
            "type": "object",
            "properties": {
              "public_access": { "type": "boolean" },
              "encryption_at_rest": { "type": "boolean" },
              "iam_attached": { "type": "boolean" }
            }
          }
        }
      },
      "ProvidersResponse": {
        "type": "object",
        "properties": {
          "providers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "$ref": "#/components/schemas/Provider" },
                "name": { "type": "string" },
                "services": { "type": "array", "items": { "type": "string" } },
                "regions": { "type": "integer" },
                "last_pricing_update": { "type": "string" }
              }
            }
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "properties": {
          "agent_id": { "type": "string" },
          "billing_status": { "type": "string", "enum": ["free", "active", "grace_period", "suspended"] },
          "free_calls_remaining": { "type": "integer" },
          "spending_cap": { "type": "number" },
          "api_calls_today": { "type": "integer" },
          "api_calls_limit": { "type": "integer" },
          "total_infrastructure_deployed": { "type": "integer" },
          "total_spend_managed": { "type": "number" },
          "budget_remaining": { "type": "number" }
        }
      },
      "ActivateResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "setup_url": { "type": "string", "format": "uri" },
          "session_id": { "type": "string" },
          "pricing": {
            "type": "object",
            "properties": {
              "estimate": { "type": "string" },
              "query_basic": { "type": "string" },
              "query_full": { "type": "string" },
              "validate": { "type": "string" }
            }
          },
          "spending_cap": { "type": "number" },
          "message": { "type": "string" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "service": { "type": "string" },
          "status": { "type": "string" },
          "version": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "suggestions": { "type": "array", "items": { "type": "string" } }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing Authorization Bearer token" } }
          }
        }
      },
      "PaymentRequired": {
        "description": "Free tier exhausted or spending cap reached",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "error": { "code": "CREDITS_EXHAUSTED", "message": "Free tier exhausted. Activate billing at /api/v1/billing/activate to continue." } }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests",
        "headers": {
          "Retry-After": {
            "schema": { "type": "integer" },
            "description": "Seconds to wait before retrying"
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Auth", "description": "Agent registration and API keys" },
    { "name": "Infrastructure", "description": "Query and estimate cloud infrastructure" },
    { "name": "Execution", "description": "Validate execution kits (Terraform/CLI)" },
    { "name": "Catalog", "description": "Browse providers and services" },
    { "name": "Billing", "description": "Usage tracking and metered billing" },
    { "name": "System", "description": "Health and status" }
  ]
}