{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "HiAgent Public API",
    "version": "1.0.0",
    "description": "The public HiAgent API exposes a service health check and a deterministic product demo. It does not expose customer accounts, workspaces, conversations, leads, sources, billing, or dashboard data. API errors use RFC 9457 problem details.",
    "contact": {
      "name": "HiAgent support",
      "url": "https://hiagent.lt/contact/"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://hiagent.lt/terms/"
    }
  },
  "servers": [
    {
      "url": "https://hiagent.lt",
      "description": "HiAgent production"
    }
  ],
  "externalDocs": {
    "description": "HiAgent API and developer resources",
    "url": "https://hiagent.lt/developers/"
  },
  "tags": [
    {
      "name": "Service",
      "description": "Read-only service availability operations."
    },
    {
      "name": "Demo",
      "description": "A deterministic demo that does not access customer data."
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/health.php": {
      "get": {
        "operationId": "getServiceHealth",
        "summary": "Get HiAgent service health",
        "description": "Checks whether the public HiAgent service and its database dependency are available. The operation is read-only and does not require authentication. The endpoint allows 120 requests per IP address per 60 seconds.",
        "tags": [
          "Service"
        ],
        "responses": {
          "200": {
            "description": "The service and its required dependency are available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/v1/demo-answer.php": {
      "post": {
        "operationId": "askDemoQuestion",
        "summary": "Ask the HiAgent product demo",
        "description": "Returns a deterministic example answer for a product, pricing, lead capture, delivery, or human handoff question. The operation does not use a model, access customer data, or change account state. It does not require authentication. The endpoint allows 80 requests per IP address per hour.",
        "tags": [
          "Demo"
        ],
        "requestBody": {
          "required": true,
          "description": "The question to match against the fixed HiAgent demo knowledge.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DemoQuestion"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A deterministic demo answer and its example source metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DemoResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "413": {
            "$ref": "#/components/responses/ContentTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "description": "Current public service health.",
        "required": [
          "ok"
        ],
        "additionalProperties": false,
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true,
            "description": "Confirms that the service and its database dependency are available.",
            "examples": [
              true
            ]
          }
        }
      },
      "DemoQuestion": {
        "type": "object",
        "description": "A question for the fixed HiAgent product demo.",
        "required": [
          "question"
        ],
        "properties": {
          "question": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "pattern": ".*\\S.*",
            "description": "A plain-text product or customer-support question.",
            "examples": [
              "How does human handoff work?"
            ]
          }
        }
      },
      "DemoResponse": {
        "type": "object",
        "description": "The successful demo response envelope.",
        "required": [
          "data"
        ],
        "additionalProperties": false,
        "properties": {
          "data": {
            "$ref": "#/components/schemas/DemoAnswer"
          }
        }
      },
      "DemoAnswer": {
        "type": "object",
        "description": "A fixed demo answer with example grounding metadata.",
        "required": [
          "reply",
          "source",
          "confidence",
          "leadPrompt"
        ],
        "additionalProperties": false,
        "properties": {
          "reply": {
            "type": "string",
            "description": "The deterministic answer text.",
            "examples": [
              "When confidence is low or the visitor asks for help, HiAgent can route the conversation for human review instead of inventing an answer."
            ]
          },
          "source": {
            "type": "string",
            "description": "The example HiAgent knowledge source matched by the demo.",
            "examples": [
              "Human handoff rules"
            ]
          },
          "confidence": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "An example confidence percentage from zero through 100.",
            "examples": [
              84
            ]
          },
          "leadPrompt": {
            "type": "boolean",
            "description": "Whether this demo answer suggests collecting lead details.",
            "examples": [
              true
            ]
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "description": "An RFC 9457 problem details response. The error field remains for compatibility with existing HiAgent clients.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "message",
          "resolution",
          "error"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "description": "The problem type identifier. about:blank uses the HTTP status meaning.",
            "examples": [
              "about:blank"
            ]
          },
          "title": {
            "type": "string",
            "description": "A short summary that is stable for the HTTP status.",
            "examples": [
              "Bad Request"
            ]
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "The HTTP status code generated for this occurrence.",
            "examples": [
              400
            ]
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation for this occurrence.",
            "examples": [
              "Question is required."
            ]
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "The request path where this occurrence happened.",
            "examples": [
              "/api/v1/demo-answer.php"
            ]
          },
          "code": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$",
            "description": "A stable machine-readable HiAgent error code.",
            "examples": [
              "invalid_request"
            ]
          },
          "message": {
            "type": "string",
            "description": "A concise error message for agent and CLI output.",
            "examples": [
              "Question is required."
            ]
          },
          "resolution": {
            "type": "string",
            "description": "A direct action that can resolve or recover from the error.",
            "examples": [
              "Review the request fields and send valid JSON."
            ]
          },
          "error": {
            "type": "string",
            "description": "The legacy HiAgent error message retained for client compatibility.",
            "examples": [
              "Question is required."
            ]
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The JSON body is invalid or a required field is missing.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "The request uses an HTTP method that this operation does not support.",
        "headers": {
          "Allow": {
            "description": "The HTTP method supported by this operation.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "ContentTooLarge": {
        "description": "The JSON request body is larger than 256 KiB.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "The client exceeded the operation rate limit.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "HiAgent could not complete the request because of an internal or dependency failure.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    }
  }
}