endpoint-validator

Endpoint Validator Skill

Deterministic HTTP endpoint validation following a Discover, Validate, Report pattern. Finds endpoints, tests each against expectations, and produces machine-readable results with clear pass/fail verdicts and CI-compatible exit codes.

Reference Loading Table

Signal	Load These Files	Why
Security header WARNs, HSTS/CSP/X-Frame issues	security-headers.md	Routes to the matching deep reference
Config errors, hardcoded IPs, timeout problems	endpoint-config-preferred-patterns.md	Routes to the matching deep reference
401/403 failures, Bearer/API-key/cookie auth	auth-endpoint-patterns.md	Routes to the matching deep reference

Instructions

Phase 1: DISCOVER

Goal: Locate or receive endpoint definitions before making any requests.

Step 1: Read repository CLAUDE.md

Check for and follow any repository-level CLAUDE.md before running validation. It may contain base URL conventions, environment variable names, or endpoint paths relevant to the project.

Step 2: Search for endpoint configuration

Look for definitions in priority order:

1. endpoints.json in project root
2. tests/endpoints.json
3. Inline specification provided by user or calling agent

Prefer config files checked into version control over ad-hoc endpoint lists. Manually listing endpoints every run leads to drift and missed endpoints.

Step 3: Parse and validate configuration

Configuration must contain base_url and at least one endpoint:

{
  "base_url": "http://localhost:8000",
  "endpoints": [
    {"path": "/health", "expect_status": 200},
    {"path": "/api/v1/users", "expect_key": "data", "timeout": 10},
    {"path": "/api/v1/search?q=test", "max_time": 2.0}
  ]
}

Each endpoint supports these fields:

• path (required): URL path appended to base_url
• expect_status (default: 200): Expected HTTP status code
• expect_key (optional): Top-level JSON key that must exist in response. Only top-level key presence is checked -- full JSON schema validation is out of scope.
• timeout (default: 5): Request timeout in seconds. The 5-second default prevents hanging on unresponsive endpoints.
• max_time (optional): Fail if response exceeds this threshold in seconds
• method (optional): HTTP method. Defaults to GET. POST/PUT/DELETE require explicit configuration with a request body -- send mutating requests only when the user explicitly configures them.
• headers (optional): Additional headers per endpoint (e.g., Accept, Content-Type, Authorization)