{
  "openapi": "3.0.0",
  "info": {
    "title": "StackScope API",
    "description": "Agent-Ready Tech Stack & Domain Intelligence Micro-API. Fast, structured detection of frontend frameworks, CMS, analytics, CDN infrastructure, security headers, and DNS records.",
    "version": "1.0.0",
    "contact": {
      "name": "AgentLabs Support",
      "url": "https://stackscope.agentlabs.workers.dev"
    }
  },
  "servers": [
    {
      "url": "https://stackscope.agentlabs.workers.dev",
      "description": "Production Cloudflare Edge Server"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Service Health Check",
        "description": "Returns operational status and active endpoints.",
        "responses": {
          "200": {
            "description": "Service is healthy and ready for queries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ONLINE"
                    },
                    "service": {
                      "type": "string",
                      "example": "StackScope API"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/scan": {
      "get": {
        "summary": "Inspect Target Domain (GET)",
        "description": "Extracts tech stack, security posture grade, DNS info, and metadata for a given URL.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Target website URL or domain name (e.g. 'https://github.com' or 'shopify.com')",
            "schema": {
              "type": "string",
              "example": "https://github.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful domain scan report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing URL parameter"
          },
          "500": {
            "description": "Scan or network error"
          }
        }
      },
      "post": {
        "summary": "Inspect Target Domain (POST)",
        "description": "Submits target URL inside JSON payload for automation and agent workflows.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "example": "https://vercel.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful domain scan report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tech": {
      "get": {
        "summary": "Specialized Tech Stack Detection",
        "description": "Identifies frontend frameworks, libraries, CMS, and payment providers for a target domain.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Target domain or URL (e.g. 'stripe.com')",
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detected technologies list"
          }
        }
      }
    },
    "/v1/security": {
      "get": {
        "summary": "Specialized Security Headers Audit",
        "description": "Evaluates HSTS, CSP, X-Frame-Options, and security posture with an A+ through F grading scale.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Target domain or URL (e.g. 'github.com')",
            "schema": {
              "type": "string",
              "example": "github.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Security headers audit and score"
          }
        }
      }
    },
    "/v1/lead-intel": {
      "get": {
        "summary": "Specialized Lead & Corporate Email Intelligence",
        "description": "Resolves MX, SPF, DMARC, and nameserver providers via sub-50ms DNS-over-HTTPS.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Target domain or URL (e.g. 'shopify.com')",
            "schema": {
              "type": "string",
              "example": "shopify.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Email infrastructure and lead intelligence data"
          }
        }
      }
    },
    "/v1/remediate": {
      "get": {
        "summary": "Specialized 1-Click DevOps Remediation",
        "description": "Generates drop-in Nginx add_header directives and vercel.json configurations for missing security headers.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Target domain to inspect and remediate automatically",
            "schema": {
              "type": "string",
              "example": "vercel.com"
            }
          },
          {
            "name": "missing",
            "in": "query",
            "required": false,
            "description": "Comma-separated list of missing headers (e.g. 'Content-Security-Policy,Permissions-Policy')",
            "schema": {
              "type": "string",
              "example": "Permissions-Policy,Strict-Transport-Security"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ready-to-deploy Nginx and Vercel configuration snippets"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScanResponse": {
        "type": "object",
        "properties": {
          "target": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "example": "https://github.com"
              },
              "hostname": {
                "type": "string",
                "example": "github.com"
              },
              "status_code": {
                "type": "integer",
                "example": 200
              },
              "fetch_status": {
                "type": "string",
                "example": "SUCCESS"
              }
            }
          },
          "technologies": {
            "type": "object",
            "properties": {
              "total_detected": {
                "type": "integer",
                "example": 4
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "React"
                    },
                    "category": {
                      "type": "string",
                      "example": "JavaScript Library"
                    },
                    "confidence": {
                      "type": "number",
                      "example": 0.95
                    },
                    "evidence": {
                      "type": "string",
                      "example": "html_pattern: data-reactroot"
                    }
                  }
                }
              }
            }
          },
          "security_posture": {
            "type": "object",
            "properties": {
              "score": {
                "type": "integer",
                "example": 85
              },
              "grade": {
                "type": "string",
                "example": "A"
              },
              "missing_headers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "scan_meta": {
            "type": "object",
            "properties": {
              "api_version": {
                "type": "string",
                "example": "1.0.0"
              },
              "serverless_runtime": {
                "type": "string",
                "example": "cloudflare_workers"
              },
              "timestamp": {
                "type": "string",
                "example": "2026-09-04T12:00:00Z"
              }
            }
          }
        }
      }
    }
  }
}