{
  "openapi": "3.1.1",
  "info": {
    "title": "AI Smarty Public Integration API",
    "version": "1.0.0",
    "description": "Public discovery, health, and browser-embed endpoints for AI Smarty. Widget endpoints are origin-scoped browser integrations, not a general management API.",
    "contact": {
      "name": "AI Smarty",
      "url": "https://aismarty.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://aismarty.com"
    }
  ],
  "externalDocs": {
    "description": "AI Smarty developer resources",
    "url": "https://aismarty.com/developers"
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "Unauthenticated API discovery and liveness endpoints."
    },
    {
      "name": "Website embed",
      "description": "Public browser endpoints used by published AI Smarty website embeds."
    }
  ],
  "paths": {
    "/api": {
      "get": {
        "operationId": "getPublicApiIndex",
        "summary": "Discover AI Smarty public API resources",
        "tags": ["Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "Canonical API discovery links.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiIndex" }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check API process liveness",
        "description": "A lightweight liveness check. It intentionally does not test database, queue, or storage dependencies.",
        "tags": ["Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "The web process is responding.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          }
        }
      }
    },
    "/api/widget/{agentId}/loader.js": {
      "get": {
        "operationId": "getWidgetLoader",
        "summary": "Load a published AI agent website embed",
        "description": "Returns the JavaScript loader for a published AI agent. Customers should copy the exact versioned URL from the AI Smarty Deploy tab.",
        "tags": ["Website embed"],
        "security": [],
        "parameters": [{ "$ref": "#/components/parameters/AgentId" }],
        "responses": {
          "200": {
            "description": "Executable browser loader or a safe no-op loader when the agent is unavailable.",
            "content": {
              "application/javascript": {
                "schema": { "type": "string" }
              }
            }
          },
          "400": {
            "description": "The agent identifier is malformed.",
            "content": {
              "application/javascript": {
                "schema": { "type": "string" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/public/bots/{agentId}/bootstrap": {
      "post": {
        "operationId": "bootstrapWidget",
        "summary": "Initialize a published AI agent browser session",
        "description": "Validates the embedding origin, returns public widget configuration, and issues a short-lived token for later widget requests. This endpoint is called by the generated website embed.",
        "tags": ["Website embed"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/AgentId" },
          {
            "name": "Origin",
            "in": "header",
            "required": false,
            "description": "Browser origin used for the AI agent's deployment allowlist or active-origin lock.",
            "schema": { "type": "string", "format": "uri" }
          },
          {
            "name": "X-Parent-Origin",
            "in": "header",
            "required": false,
            "description": "Embedding-page origin supplied by the trusted iframe flow. It is accepted only with matching browser context headers.",
            "schema": { "type": "string", "format": "uri" }
          }
        ],
        "responses": {
          "200": {
            "description": "Widget configuration and a short-lived runtime token.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BootstrapResponse" }
              }
            }
          },
          "403": {
            "description": "The agent, deployment state, or request origin is not eligible.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WidgetError" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": {
            "description": "The AI agent is temporarily offline.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentOffline" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "AgentId": {
        "name": "agentId",
        "in": "path",
        "required": true,
        "description": "Published AI agent UUID supplied by the Deploy tab.",
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "The public request rate limit was exceeded.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": { "type": "integer", "minimum": 0 }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/RateLimitError" }
          }
        }
      }
    },
    "schemas": {
      "ApiIndex": {
        "type": "object",
        "required": [
          "name",
          "version",
          "description",
          "documentation",
          "openapi",
          "status",
          "errorExample"
        ],
        "properties": {
          "name": { "type": "string", "const": "AI Smarty Public API" },
          "version": { "type": "string" },
          "description": { "type": "string" },
          "documentation": { "type": "string", "format": "uri" },
          "openapi": { "type": "string", "format": "uri" },
          "status": { "type": "string", "format": "uri" },
          "errorExample": { "$ref": "#/components/schemas/ApiError" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "timestamp", "tier", "testHooks"],
        "properties": {
          "status": { "type": "string", "const": "ok" },
          "timestamp": { "type": "string", "format": "date-time" },
          "tier": {
            "type": "string",
            "enum": ["local", "development", "staging", "production"]
          },
          "testHooks": { "type": "boolean" }
        }
      },
      "BootstrapResponse": {
        "type": "object",
        "required": ["success", "token", "expiresIn", "config"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "token": { "type": "string" },
          "expiresIn": { "type": "integer", "minimum": 1 },
          "config": {
            "type": "object",
            "required": [
              "botId",
              "botName",
              "greeting",
              "widgetConfig",
              "suggestedQuestions",
              "suggestedQuestionsEnabled"
            ],
            "properties": {
              "botId": { "type": "string", "format": "uuid" },
              "botName": { "type": "string" },
              "personaName": { "type": ["string", "null"] },
              "greeting": { "type": "string" },
              "avatarUrl": { "type": ["string", "null"], "format": "uri" },
              "widgetConfig": { "type": "object", "additionalProperties": true },
              "suggestedQuestions": { "type": "array", "items": { "type": "string" } },
              "suggestedQuestionsEnabled": { "type": "boolean" }
            }
          }
        }
      },
      "WidgetError": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "AgentOffline": {
        "type": "object",
        "required": ["success", "status", "reason", "error", "message"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "status": { "type": "string", "const": "agent_offline" },
          "reason": { "type": "string", "enum": ["system", "admin"] },
          "error": { "type": "string", "const": "agent_offline" },
          "message": { "type": "string" }
        }
      },
      "RateLimitError": {
        "type": "object",
        "required": ["error", "message", "retryAfter"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "retryAfter": { "type": "number", "minimum": 0 }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error", "code", "resolution"],
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string" },
          "resolution": { "type": "string" }
        }
      }
    }
  }
}