{
  "openapi": "3.0.3",
  "info": {
    "title": "HuntProAI API",
    "version": "1.0.0",
    "description": "Advanced AI-powered animal detection and analysis API for wildlife images. Provides species identification, gender classification (including turkey Gobblers vs Hens), antler analysis for deer, pig color detection for genetics research, bounding boxes, confidence scores, and camera brand extraction. Privacy-focused: Images are not stored and are not used for training.",
    "contact": {
      "name": "AI Concepts LLC",
      "email": "marketing@huntpro.app",
      "url": "https://www.huntpro.app"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://api.huntpro-ai.com"
    },
    "x-privacy": {
      "imageStorage": "Images are not stored on our servers",
      "trainingData": "Images are not used for model training or improvement",
      "encryption": "All data is encrypted in transit using industry-standard HTTPS/TLS",
      "dataRetention": "No image data is retained after API response is returned"
    }
  },
  "servers": [
    {
      "url": "https://api.huntpro-ai.com",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Image Analysis",
      "description": "AI-powered animal detection and analysis endpoints"
    }
  ],
  "paths": {
    "/AnalyzeImageAdvancedByURL": {
      "post": {
        "tags": ["Image Analysis"],
        "summary": "Analyze image from URL",
        "description": "Analyze an image from a URL and return detected animals with detailed attributes including species, gender, bounding boxes, confidence levels, and deer-specific analysis.",
        "operationId": "analyzeImageByURL",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/URLAnalysisRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic analysis",
                  "value": {
                    "ImageURL": "https://example.com/wildlife.jpg",
                    "Key": "DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a"
                  }
                },
                "filtered": {
                  "summary": "Filter for specific species",
                  "value": {
                    "ImageURL": "https://example.com/deer.jpg",
                    "Key": "DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a",
                    "animals": ["White-tailed Deer", "Turkey"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalysisResponse"
                },
                "examples": {
                  "deer_detection": {
                    "summary": "Deer detection with details",
                    "value": {
                      "detections": [
                        {
                          "species": "White-tailed Deer",
                          "gender": "Male",
                          "location": 1,
                          "confidenceLevel": 95,
                          "antlerRank": 8,
                          "boundingbox": {
                            "left": 0.25,
                            "top": 0.15,
                            "width": 0.45,
                            "height": 0.65
                          },
                          "deerDetails": {
                            "antlerRank": 8,
                            "numberOfAntlerPoints": 10,
                            "ageCategory": "Mature",
                            "ageReasoning": "Well-developed antlers with 10 points indicate a mature buck, likely 4-6 years old based on antler mass and body structure."
                          },
                          "reasoning": "Large body size, prominent antlers with high point count, and overall body condition suggest a mature male white-tailed deer."
                        }
                      ],
                      "dayTime": true,
                      "make": "Reconyx"
                    }
                  },
                  "pig_detection": {
                    "summary": "Pig detection with color for genetics",
                    "value": {
                      "detections": [
                        {
                          "species": "Pig",
                          "gender": "Unknown",
                          "location": 1,
                          "confidenceLevel": 92,
                          "color": "Black",
                          "boundingbox": {
                            "left": 0.30,
                            "top": 0.40,
                            "width": 0.40,
                            "height": 0.50
                          },
                          "reasoning": "Distinctive body shape and features confirm pig identification with black coloration suitable for genetics research."
                        }
                      ],
                      "dayTime": true,
                      "make": "Browning"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/AnalyzeImageAdvancedBase64": {
      "post": {
        "tags": ["Image Analysis"],
        "summary": "Analyze image from Base64",
        "description": "Analyze an image provided as Base64-encoded data. Returns the same format as the URL endpoint.",
        "operationId": "analyzeImageByBase64",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Base64AnalysisRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic analysis with Base64 image",
                  "value": {
                    "Base64Image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
                    "Key": "DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a"
                  }
                },
                "filtered": {
                  "summary": "Filter for specific species",
                  "value": {
                    "Base64Image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
                    "Key": "DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a",
                    "animals": ["Turkey", "Pig"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalysisResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "URLAnalysisRequest": {
        "type": "object",
        "required": ["ImageURL", "Key"],
        "properties": {
          "ImageURL": {
            "type": "string",
            "format": "uri",
            "description": "URL of the image to analyze. Must be publicly accessible.",
            "example": "https://example.com/wildlife.jpg"
          },
          "Key": {
            "type": "string",
            "description": "Your API key. Use DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a for testing. Contact marketing@huntpro.app for production keys.",
            "example": "DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a"
          },
          "animals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional array of species to filter. Only animals in this list will be detected. If empty or omitted, all supported species will be detected.",
            "example": ["White-tailed Deer", "Turkey", "Pig"]
          }
        }
      },
      "Base64AnalysisRequest": {
        "type": "object",
        "required": ["Base64Image", "Key"],
        "properties": {
          "Base64Image": {
            "type": "string",
            "description": "Base64-encoded image data with data URI prefix (e.g., data:image/jpeg;base64,...). Supported formats: JPEG, JPG, PNG.",
            "example": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
          },
          "Key": {
            "type": "string",
            "description": "Your API key. Use DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a for testing. Contact marketing@huntpro.app for production keys.",
            "example": "DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a"
          },
          "animals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional array of species to filter. Only animals in this list will be detected. If empty or omitted, all supported species will be detected.",
            "example": ["White-tailed Deer", "Turkey"]
          }
        }
      },
      "AnalysisResponse": {
        "type": "object",
        "properties": {
          "detections": {
            "type": "array",
            "description": "Array of detected animals in the image",
            "items": {
              "$ref": "#/components/schemas/Detection"
            }
          },
          "dayTime": {
            "type": "boolean",
            "description": "True if image was taken during daytime, false if nighttime"
          },
          "make": {
            "type": "string",
            "description": "Camera brand extracted from image EXIF metadata (if available)",
            "example": "Reconyx"
          }
        }
      },
      "Detection": {
        "type": "object",
        "properties": {
          "species": {
            "type": "string",
            "description": "Detected animal species",
            "example": "White-tailed Deer"
          },
          "gender": {
            "type": "string",
            "description": "Animal gender (Male/Female/Unknown)",
            "enum": ["Male", "Female", "Unknown"],
            "example": "Male"
          },
          "location": {
            "type": "integer",
            "description": "Location identifier for the detection",
            "example": 1
          },
          "confidenceLevel": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Confidence level of the detection (0-100)",
            "example": 95
          },
          "color": {
            "type": "string",
            "description": "Animal color (present only for pig species, used for genetics research)",
            "example": "Black"
          },
          "antlerRank": {
            "type": "integer",
            "description": "Antler rank (for deer species only)",
            "example": 8
          },
          "boundingbox": {
            "$ref": "#/components/schemas/BoundingBox"
          },
          "deerDetails": {
            "$ref": "#/components/schemas/DeerDetails"
          },
          "reasoning": {
            "type": "string",
            "description": "AI-generated reasoning explaining the classification decision",
            "example": "Large body size, prominent antlers with high point count, and overall body condition suggest a mature male white-tailed deer."
          }
        }
      },
      "BoundingBox": {
        "type": "object",
        "description": "Normalized bounding box coordinates (0-1 relative to image dimensions)",
        "properties": {
          "left": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "description": "Left coordinate (normalized, 0-1)",
            "example": 0.25
          },
          "top": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "description": "Top coordinate (normalized, 0-1)",
            "example": 0.15
          },
          "width": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "description": "Width (normalized, 0-1)",
            "example": 0.45
          },
          "height": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "description": "Height (normalized, 0-1)",
            "example": 0.65
          }
        }
      },
      "DeerDetails": {
        "type": "object",
        "description": "Detailed deer-specific analysis (present only for deer species)",
        "properties": {
          "antlerRank": {
            "type": "integer",
            "description": "Numerical rank of antler quality/size",
            "example": 8
          },
          "numberOfAntlerPoints": {
            "type": "integer",
            "description": "Total number of antler points",
            "example": 10
          },
          "ageCategory": {
            "type": "string",
            "description": "Age category based on antler development",
            "enum": ["Young", "Mature", "Trophy"],
            "example": "Mature"
          },
          "ageReasoning": {
            "type": "string",
            "description": "AI-generated reasoning for age classification",
            "example": "Well-developed antlers with 10 points indicate a mature buck, likely 4-6 years old based on antler mass and body structure."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message",
            "example": "Invalid API key"
          },
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "UNAUTHORIZED"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "body",
        "name": "Key",
        "description": "API key passed in the request body. Use DEMO_KEY_a7f3c8e1-4b2d-9c5f-8a3e-1d6b9f2c4e7a for testing. Contact marketing@huntpro.app to obtain a production key."
      }
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ],
  "externalDocs": {
    "description": "Full interactive documentation and demo",
    "url": "https://api.huntpro-ai.com"
  }
}