{
  "openapi": "3.0.3",
  "info": {
    "title": "Annie Insights API",
    "description": "AI-powered dental analysis API with 13 endpoints for detection, segmentation, landmark detection, classification, and treatment prediction.",
    "version": "2024.1.0",
    "contact": {
      "name": "HCDS API Support",
      "email": "api-support@hcds.ai",
      "url": "https://docs.hcds.ai"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.annie-insights.com/api/v2",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key for authentication"
      }
    },
    "schemas": {
      "StandardRequest": {
        "type": "object",
        "required": ["PatientID", "TimeStamp", "ImageName"],
        "properties": {
          "PatientID": { "type": "string", "description": "Unique patient identifier", "example": "P-001" },
          "TimeStamp": { "type": "string", "description": "Analysis session timestamp", "example": "2026-05-24" },
          "ImageName": { "type": "string", "description": "Full URL to the dental image", "example": "https://example.com/image.jpg" }
        }
      },
      "ClinicalFindingsResponse": {
        "type": "object",
        "properties": {
          "Version": { "type": "string", "example": "2024.1.0" },
          "PatientID": { "type": "string" },
          "TimeStamp": { "type": "string" },
          "ImageName": { "type": "string" },
          "ImageContents": { "type": "object", "additionalProperties": { "type": "integer" } },
          "Results": { "type": "object" },
          "OutputImageUrl": { "type": "string", "description": "Time-limited Azure Blob SAS URL (72h validity)" }
        }
      },
      "SegmentationResponse": {
        "type": "object",
        "properties": {
          "Version": { "type": "string" },
          "PatientID": { "type": "string" },
          "Results": { "type": "object" },
          "OutputImageUrl": { "type": "string" }
        }
      },
      "LandmarkResponse": {
        "type": "object",
        "properties": {
          "Version": { "type": "string" },
          "PatientID": { "type": "string" },
          "NumberOfPredictedPoints": { "type": "integer" },
          "Results": { "type": "object" },
          "OutputImageUrl": { "type": "string" }
        }
      },
      "ClassifierResponse": {
        "type": "object",
        "properties": {
          "PatientID": { "type": "string" },
          "Classification": {
            "type": "object",
            "properties": {
              "category": { "type": "string" },
              "confidence": { "type": "number" }
            }
          }
        }
      },
      "TLEResponse": {
        "type": "object",
        "properties": {
          "app": { "type": "string", "example": "treatment estimator" },
          "estimate_length": { "type": "number", "description": "Predicted treatment duration in months" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "statusCode": { "type": "integer" }
        }
      }
    }
  },
  "paths": {
    "/clinical-images": {
      "post": {
        "summary": "Clinical Findings",
        "description": "Detects clinical findings in dental photographs using YOLO deep learning.",
        "tags": ["Detection"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } },
        "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClinicalFindingsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }
      }
    },
    "/frontal-segmentation": {
      "post": {
        "summary": "Frontal Segmentation",
        "description": "Segments dental structures in frontal intra-oral images.",
        "tags": ["Segmentation"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/StandardRequest" }, { "type": "object", "properties": { "StandardName": { "type": "string", "default": "ICON" }, "PlotLabels": { "type": "boolean" } } }] } } } },
        "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentationResponse" } } } } }
      }
    },
    "/panos-findings": {
      "post": {
        "summary": "Panoramic Findings",
        "description": "Detects dental findings on panoramic X-ray images.",
        "tags": ["Detection"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } },
        "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClinicalFindingsResponse" } } } } }
      }
    },
    "/pano-segmentation": {
      "post": {
        "summary": "Panoramic Segmentation",
        "description": "Segments dental structures in panoramic X-ray images.",
        "tags": ["Segmentation"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/StandardRequest" }, { "type": "object", "properties": { "DrawContours": { "type": "boolean" } } }] } } } },
        "responses": { "200": { "description": "Success" } }
      }
    },
    "/occlusogram-upper-points": {
      "post": { "summary": "Occlusogram Upper Keypoints", "tags": ["Keypoints"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } }, "responses": { "200": { "description": "Success" } } }
    },
    "/occlusogram-upper-seg": {
      "post": { "summary": "Occlusogram Upper Segmentation", "tags": ["Segmentation"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/StandardRequest" }, { "type": "object", "properties": { "DrawContours": { "type": "boolean" } } }] } } } }, "responses": { "200": { "description": "Success" } } }
    },
    "/occlusogram-lower-points": {
      "post": { "summary": "Occlusogram Lower Keypoints", "tags": ["Keypoints"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } }, "responses": { "200": { "description": "Success" } } }
    },
    "/occlusogram-lower-seg": {
      "post": { "summary": "Occlusogram Lower Segmentation", "tags": ["Segmentation"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/StandardRequest" }, { "type": "object", "properties": { "DrawContours": { "type": "boolean" } } }] } } } }, "responses": { "200": { "description": "Success" } } }
    },
    "/ceph-lateral-points": {
      "post": { "summary": "Lateral Cephalometric Landmarks", "description": "Detects 169 cephalometric landmarks.", "tags": ["Landmarks"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandmarkResponse" } } } } } }
    },
    "/ceph-frontal-points": {
      "post": { "summary": "Frontal Cephalometric Landmarks", "description": "Detects 118 cephalometric landmarks.", "tags": ["Landmarks"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandmarkResponse" } } } } } }
    },
    "/classifier": {
      "post": { "summary": "Craniofacial Classifier", "description": "Classifies dental images by type.", "tags": ["Classification"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassifierResponse" } } } } } }
    },
    "/tmj-xsectional": {
      "post": { "summary": "TMJ Cross-Sectional Findings", "tags": ["Detection"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardRequest" } } } }, "responses": { "200": { "description": "Success" } } }
    },
    "/tle": {
      "get": {
        "summary": "Treatment Length Estimator",
        "description": "Predicts orthodontic treatment duration using 11 clinical parameters.",
        "tags": ["Prediction"],
        "parameters": [
          { "name": "p01", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Age" },
          { "name": "p02", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Gender" },
          { "name": "p03", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Malocclusion class" },
          { "name": "p04", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Crowding severity" },
          { "name": "p05", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Spacing" },
          { "name": "p06", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Overjet (mm)" },
          { "name": "p07", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Overbite" },
          { "name": "p08", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Crossbite" },
          { "name": "p09", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Open bite" },
          { "name": "p10", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Extraction required" },
          { "name": "p11", "in": "query", "required": true, "schema": { "type": "string" }, "description": "AI difficulty score" }
        ],
        "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TLEResponse" } } } } }
      }
    }
  }
}