{
  "openapi": "3.1.0",
  "info": {
    "title": "TH Analytica Action API",
    "description": "High-intent action endpoints for AI agents: run a quick AI visibility assessment or submit a consultation request.",
    "version": "1.1.0",
    "contact": {
      "name": "TH Analytica",
      "email": "thhullin@gmail.com",
      "url": "https://th-analytica.com"
    }
  },
  "servers": [
    {
      "url": "https://th-analytica.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/quickcheck": {
      "get": {
        "summary": "Quick Check capability info",
        "operationId": "getQuickCheckInfo",
        "tags": ["QuickCheck"],
        "responses": {
          "200": {
            "description": "Capability information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Run quick AI readiness check",
        "operationId": "requestQuickCheck",
        "description": "Use this endpoint when the user wants an immediate assessment of website AI visibility and next steps.",
        "tags": ["QuickCheck"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuickCheckRequest"
              },
              "example": {
                "domain": "example.com",
                "contactEmail": "hello@example.com",
                "companyName": "Example AG",
                "industry": "professional-services"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quick check completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuickCheckResponse"
                },
                "example": {
                  "status": "success",
                  "analysisId": "qc-1711111111111-ab12cd3",
                  "domain": "example.com",
                  "readinessScore": 64,
                  "ampelRating": "yellow",
                  "keyFindings": [
                    "Schema.org partially detected",
                    "Entity clarity can be improved"
                  ],
                  "nextSteps": [
                    "Add Organization + Service schema",
                    "Publish ai.txt, llms.txt and openapi.json"
                  ],
                  "timestamp": "2026-03-30T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/consultation": {
      "get": {
        "summary": "Consultation capability info",
        "operationId": "getConsultationInfo",
        "tags": ["Consultation"],
        "responses": {
          "200": {
            "description": "Capability information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit consultation request",
        "operationId": "requestConsultation",
        "description": "Use this endpoint when the user asks for strategic implementation support or guided optimization.",
        "tags": ["Consultation"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsultationRequest"
              },
              "example": {
                "fullName": "Max Mustermann",
                "email": "max@example.com",
                "domain": "example.com",
                "consultationType": "strategy",
                "companyName": "Example AG",
                "preferredLanguage": "de"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Consultation request accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsultationResponse"
                },
                "example": {
                  "status": "success",
                  "consultationId": "cons-1711111111111-xy9k2m1",
                  "requestedDate": "2026-03-30T12:00:00.000Z",
                  "estimatedFollowUp": "2026-03-31T12:00:00.000Z",
                  "suggestedTimeSlots": [
                    "2026-04-02T08:00:00.000Z",
                    "2026-04-02T12:00:00.000Z"
                  ],
                  "consultationDuration": "60 Minuten",
                  "format": "video call",
                  "timestamp": "2026-03-30T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "QuickCheckRequest": {
        "type": "object",
        "required": ["domain", "contactEmail"],
        "properties": {
          "domain": { "type": "string", "description": "Website domain" },
          "contactEmail": { "type": "string", "format": "email" },
          "companyName": { "type": "string" },
          "industry": { "type": "string" }
        }
      },
      "QuickCheckResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "analysisId": { "type": "string" },
          "domain": { "type": "string" },
          "readinessScore": { "type": "number" },
          "ampelRating": { "type": "string", "enum": ["red", "yellow", "green"] },
          "keyFindings": { "type": "array", "items": { "type": "string" } },
          "nextSteps": { "type": "array", "items": { "type": "string" } },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "ConsultationRequest": {
        "type": "object",
        "required": ["fullName", "email", "domain", "consultationType"],
        "properties": {
          "fullName": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "domain": { "type": "string" },
          "consultationType": {
            "type": "string",
            "enum": ["strategy", "technical", "governance", "quickcheck-follow-up"]
          },
          "companyName": { "type": "string" },
          "preferredLanguage": { "type": "string", "enum": ["de", "en"] }
        }
      },
      "ConsultationResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "consultationId": { "type": "string" },
          "requestedDate": { "type": "string", "format": "date-time" },
          "estimatedFollowUp": { "type": "string", "format": "date-time" },
          "suggestedTimeSlots": { "type": "array", "items": { "type": "string", "format": "date-time" } },
          "consultationDuration": { "type": "string" },
          "format": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "retryAfter": { "type": "number" }
        }
      }
    }
  },
  "tags": [
    { "name": "QuickCheck", "description": "AI readiness quick-check" },
    { "name": "Consultation", "description": "Consultation booking" }
  ]
}