{ "openapi": "3.1.0", "info": { "title": "Validator Master Public Evaluation API", "version": "0.1.0", "description": "Versioned behavioral evaluation endpoints. A high score does not prove factual correctness, universal safety, certification, or compliance." }, "servers": [ { "url": "https://api.heartcodeprotocol.org" } ], "paths": { "/api/evaluate-response": { "post": { "operationId": "evaluateResponse", "summary": "Evaluate an existing AI response with Heartcode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "prompt", "response", "privacyAcknowledged" ], "properties": { "contractVersion": { "type": "string", "const": "1.0.0" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "response": { "type": "string", "minLength": 1, "maxLength": 8000 }, "privacyAcknowledged": { "type": "boolean", "const": true } } } } } }, "responses": { "200": { "description": "Versioned Heartcode evaluation", "content": { "application/json": { "schema": { "type": "object", "required": [ "contractVersion", "requestId", "completedAt", "protocolVersion", "evaluatorVersion", "evaluationScope", "evaluation" ], "properties": { "contractVersion": { "type": "string", "const": "1.0.0" }, "requestId": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "protocolVersion": { "type": "string" }, "evaluatorVersion": { "type": "string" }, "evaluationScope": { "type": "string", "const": "response_text_only" }, "evaluation": { "type": "object", "required": [ "evaluationId", "overallScore", "overallVerdict", "verdicts", "findings" ], "properties": { "evaluationId": { "type": "string" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100 }, "overallVerdict": { "type": "string", "enum": [ "pass", "fail", "needs_review" ] }, "verdicts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "findings": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "500": { "description": "Internal evaluation failure", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "503": { "description": "Public service or protected provider-spend path unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/evaluate": { "post": { "operationId": "generateAndEvaluate", "summary": "Generate through selected configured providers and evaluate returned responses", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "prompt", "providerIds", "privacyAcknowledged" ], "properties": { "contractVersion": { "type": "string", "const": "1.0.0" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "providerIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "openai", "ollama", "gemini", "anthropic", "xai", "nvidia" ] } }, "privacyAcknowledged": { "type": "boolean", "const": true } } } } } }, "responses": { "200": { "description": "Provider results plus Heartcode evaluations", "content": { "application/json": { "schema": { "type": "object", "required": [ "contractVersion", "requestId", "completedAt", "protocolVersion", "evaluatorVersion", "results" ], "properties": { "contractVersion": { "type": "string", "const": "1.0.0" }, "requestId": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "protocolVersion": { "type": "string" }, "evaluatorVersion": { "type": "string" }, "results": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Admission, quota, global-budget, concurrency, or duplicate-request limit reached", "headers": { "Retry-After": { "description": "Retry delay in seconds when the admission controller provides one", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "500": { "description": "Internal evaluation failure", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "503": { "description": "Public service or protected provider-spend path unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/arena": { "post": { "operationId": "runArena", "summary": "Run the same prompt across multiple providers and return ordered Heartcode evidence", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "prompt", "privacyAcknowledged", "providers" ], "properties": { "contractVersion": { "type": "string", "const": "1.0.0" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "privacyAcknowledged": { "type": "boolean", "const": true }, "providers": { "type": "array", "minItems": 2, "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "enum": [ "openai", "anthropic", "google", "xai", "nvidia" ] } } } } } } }, "responses": { "200": { "description": "Ordered Arena provider results and evaluations", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Admission, quota, global-budget, concurrency, or duplicate-request limit reached", "headers": { "Retry-After": { "description": "Retry delay in seconds when the admission controller provides one", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "500": { "description": "Internal evaluation failure", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "503": { "description": "Public service or protected provider-spend path unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/arena-evidence": { "post": { "operationId": "runArenaWithEvidence", "summary": "Run Arena and return same-run structured evidence", "description": "Uses the Arena request contract and the same protected provider-spend admission boundary. The evidence response is versioned separately by the Arena Evidence contract.", "requestBody": { "$ref": "#/paths/~1api~1arena/post/requestBody" }, "responses": { "200": { "description": "Arena result plus same-run evidence artifact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Admission, quota, global-budget, concurrency, or duplicate-request limit reached", "headers": { "Retry-After": { "description": "Retry delay in seconds when the admission controller provides one", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "500": { "description": "Internal evaluation failure", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "503": { "description": "Public service or protected provider-spend path unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/improvement-demo": { "post": { "operationId": "runImprovementDemo", "summary": "Run the bounded improvement demonstration", "description": "Public demonstration endpoint with its own versioned contract; consult canonical documentation before relying on the result.", "responses": { "200": { "description": "Versioned improvement-demo response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "500": { "description": "Internal evaluation failure", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "503": { "description": "Public service or protected provider-spend path unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/feedback": { "post": { "operationId": "submitFeedback", "summary": "Submit bounded private public-alpha feedback", "description": "Feedback is not an evaluation action and does not modify Heartcode or evaluator behavior.", "responses": { "201": { "description": "Feedback accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid feedback", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } }, "503": { "description": "Feedback persistence unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } }, "components": { "schemas": { "PublicError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } }, "HeartcodeEvaluation": { "type": "object", "required": [ "evaluationId", "overallScore", "overallVerdict", "verdicts", "findings" ], "properties": { "evaluationId": { "type": "string" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100 }, "overallVerdict": { "type": "string", "enum": [ "pass", "fail", "needs_review" ] }, "verdicts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "findings": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }