Validator Master Public API
Machine-readable overview of the current public evaluation endpoints and their operational boundaries.
OpenAPI
The machine-readable OpenAPI document is https://api.heartcodeprotocol.org/openapi.json. It is built from repository-owned contract constants and is regression-tested against the TypeScript validators.
Direct evaluation
POST /api/evaluate-response uses contract 1.0.0. Prompt length is limited to 2000 characters and response length to 8000 characters.
Provider-backed evaluation
POST /api/evaluate uses contract 1.0.0. The deployed public-alpha endpoint accepts exactly one provider per request; use Arena for comparisons. Supported contract provider identifiers are: openai, ollama, gemini, anthropic, xai, nvidia. Availability depends on runtime configuration and admission controls.
Public-alpha admission can return HTTP 429 for quota, global-budget, concurrency, or duplicate-request limits. When a retry interval is known, the response includes Retry-After.
Arena
POST /api/arena uses contract 1.0.0. It accepts 2–5 distinct provider identifiers from: openai, anthropic, google, xai, nvidia.
Arena provider-spend admission preserves global budget and kill-switch protections. Admission exhaustion can return HTTP 429 with Retry-After when available; spend disablement or kill-switch state fails closed.
Improvement demonstration
POST /api/improvement-demo requires contractVersion=1.0.0, a non-empty prompt of at most 2000 UTF-16 code units, and privacyAcknowledged=true. Optional maxIterations is an integer from 1 to 3, defaulting to 1.
The JSON body limit defaults to 16 KiB and can be configured up to 64 KiB. Admission limits can return HTTP 429 with Retry-After; provider failures can return 502 and timeouts 504.
Feedback and consent
POST /api/feedback requires contractVersion=1.0.0, a non-empty message of at most 4,000 UTF-16 code units after trimming, and all four explicit permission booleans. submitFeedback must be true; contactEmail, evaluationRef, and diagnostics each require their corresponding permission to be true. Optional permissions may remain false for anonymous feedback.
The feedback JSON body limit is 8 KiB. Accepted feedback expires from the primary feedback store after 30 days and returns HTTP 201 with ok=true and feedbackId. When email notifications are configured, notification copies have separate retention. Feedback errors use a string-valued error field, unlike evaluation errors, which use a structured error object.