{ "openapi": "3.0.0", "info": { "title": "HefestoAI API", "description": "Pre-commit code quality guardian for AI-generated code. Detects semantic drift, blocks bad AI code before production. Errors are RFC 9457 problem details (application/problem+json, schema Problem). Versioning and deprecation: see x-api-version-policy.", "version": "4.20.4", "contact": { "name": "Arturo Velasquez", "url": "https://hefestoai.narapallc.com" }, "x-logo": { "url": "https://hefestoai.narapallc.com/logo.png" }, "x-api-version-policy": { "versioning": "info.version follows the hefesto-ai release that serves the API (semantic versioning). Paths are not versioned: changes are additive within a major version.", "breaking-changes": "Removing a path, a required request field or a response field is a breaking change and only happens in a new major version, announced at least 90 days ahead in the changelog.", "deprecation": "A deprecated operation is marked deprecated: true here and answers with the Deprecation and Sunset headers (RFC 9745, RFC 8594) until removal.", "changelog": "https://hefestoai.narapallc.com/changelog.json" } }, "servers": [ { "url": "https://hefestoai.narapallc.com/api", "description": "Production" } ], "paths": { "/mcp-protocol": { "post": { "summary": "MCP Streamable HTTP endpoint (connect here)", "description": "Connect MCP clients to https://hefestoai.narapallc.com/api/mcp-protocol. JSON-RPC 2.0 over Streamable HTTP: initialize, tools/list, and tools/call. /mcp is REST discovery only and is not this endpoint.", "operationId": "mcpProtocol", "tags": [ "AI Agent Integration" ], "responses": { "200": { "description": "JSON-RPC result or JSON-RPC error (errors stay JSON-RPC, not problem details)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "202": { "description": "Notification accepted, no body" }, "400": { "description": "Invalid JSON-RPC envelope or protocol version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "403": { "description": "Origin not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "405": { "description": "Only POST and OPTIONS" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } } } }, "/mcp": { "get": { "summary": "REST discovery (not the MCP connection endpoint)", "description": "JSON capability discovery. MCP clients connect to /mcp-protocol. This path stays for discovery.", "operationId": "getMcpCapabilities", "tags": [ "AI Agent Integration" ], "responses": { "200": { "description": "HefestoAI MCP capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpResponse" } } } }, "default": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "REST discovery query (not Streamable HTTP)", "operationId": "queryMcp", "tags": [ "AI Agent Integration" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "capability": { "type": "string", "enum": [ "pricing", "install", "analyze" ] }, "query": { "type": "string" } } } } } }, "responses": { "200": { "description": "MCP discovery response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/ask": { "get": { "summary": "Ask HefestoAI a question (GET)", "operationId": "askGet", "tags": [ "Knowledge Base" ], "parameters": [ { "name": "q", "in": "query", "description": "Natural language question about HefestoAI", "schema": { "type": "string" }, "example": "what is hefestoai" } ], "responses": { "200": { "description": "Answer from HefestoAI knowledge base", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } } }, "default": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Ask HefestoAI a question (POST)", "operationId": "askPost", "tags": [ "Knowledge Base" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "example": "how does hefestoai compare to sonarqube?" } } } } } }, "responses": { "200": { "description": "Structured answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/analyze": { "get": { "summary": "Describe the hosted analyze endpoint", "operationId": "describeAnalyze", "tags": [ "AI Agent Integration" ], "responses": { "200": { "description": "Request format, limits and notes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeDescription" } } } }, "default": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Analyze files with the open-source hefesto-ai engine", "description": "Writes the submitted files to a temporary directory, runs `hefesto analyze . --no-config` (hefesto-ai, free tier) in a time-limited child process and returns the findings with rule ids and SARIF hefestoFingerprint/v1 fingerprints. Nothing is stored. Limits: 20 files, 100 KB per file, 256 KB total, 512 KB body, 20 s, 10 requests per minute per IP, shared across server instances. TypeScript, JavaScript, Java, Go, Rust and C# are analyzed with the multilang tree-sitter grammars (downloaded once per server instance; files whose grammar cannot be loaded are listed in files_not_analyzed). No .hefesto.yaml is read.", "operationId": "analyzeFiles", "tags": [ "AI Agent Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "maxLength": 200, "description": "Relative POSIX path; letters, digits, '_', '.', '-'; no '..', no absolute paths, at most 8 levels" }, "content": { "type": "string", "description": "UTF-8 text, at most 100 KB" } } } }, "code": { "type": "string", "description": "Single snippet, used when files is not given" }, "language": { "type": "string", "description": "Language of code (default python)" }, "severity": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "default": "LOW" }, "format": { "type": "string", "enum": [ "json", "sarif" ], "default": "json" } } } } } }, "responses": { "200": { "description": "Analysis result: analyzed, engine, summary, findings[{rule_id, severity, level, file, line, message, fingerprint}], files_not_analyzed, stored=false, limits, notes, and sarif when format=sarif", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "411": { "description": "Content-Length missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Too many files or too much data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "description": "Analysis took longer than 20 s", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "schemas": { "McpResponse": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "capabilities": { "type": "object" }, "pricing": { "type": "object" }, "install": { "type": "string" } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details. Legacy members (error, message) may also be present.", "required": [ "type", "title", "status", "detail", "code", "resolution" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://hefestoai.narapallc.com/problems/rate_limited" }, "title": { "type": "string", "example": "Too Many Requests" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "example": 429 }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable error code", "example": "rate_limited" }, "resolution": { "type": "string", "description": "What the caller can do next" }, "error": { "type": "string", "description": "Legacy alias of code (or a human message on /subscribe)" }, "message": { "type": "string", "description": "Legacy alias of detail (/analyze)" } }, "additionalProperties": true }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "nullable": true }, "result": { "type": "object" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } } } }, "AskResponse": { "type": "object", "required": [ "source", "response", "endpoints" ], "properties": { "query": { "type": "string", "nullable": true }, "source": { "type": "string" }, "response": { "type": "object", "additionalProperties": true }, "endpoints": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "AnalyzeDescription": { "type": "object", "additionalProperties": true, "properties": { "limits": { "type": "object", "additionalProperties": { "type": "integer" } }, "notes": { "type": "array", "items": { "type": "string" } } } }, "Finding": { "type": "object", "properties": { "rule_id": { "type": "string" }, "severity": { "type": "string", "nullable": true, "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW", null ] }, "level": { "type": "string", "nullable": true }, "file": { "type": "string", "nullable": true }, "line": { "type": "integer", "nullable": true }, "message": { "type": "string" }, "fingerprint": { "type": "string", "nullable": true } } }, "AnalyzeResult": { "type": "object", "required": [ "analyzed", "engine", "summary", "findings", "stored" ], "properties": { "analyzed": { "type": "boolean", "enum": [ true ] }, "engine": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string", "nullable": true }, "command": { "type": "string" } } }, "severity_threshold": { "type": "string" }, "summary": { "type": "object", "properties": { "files_received": { "type": "integer" }, "files_analyzed": { "type": "integer" }, "total_issues": { "type": "integer" }, "critical": { "type": "integer" }, "high": { "type": "integer" }, "medium": { "type": "integer" }, "low": { "type": "integer" }, "duration_seconds": { "type": "number" } } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "findings_truncated": { "type": "boolean" }, "files_not_analyzed": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "reason": { "type": "string" } } } }, "stored": { "type": "boolean", "enum": [ false ] }, "limits": { "type": "object", "additionalProperties": { "type": "integer" } }, "notes": { "type": "array", "items": { "type": "string" } }, "sarif": { "type": "object", "description": "SARIF 2.1.0 log, only when format=sarif" } } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "No endpoint at this path", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "MethodNotAllowed": { "description": "HTTP method not supported; see the Allow header", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Rate limited; see Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServerError": { "description": "Server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "tags": [ { "name": "AI Agent Integration", "description": "Endpoints for AI agent and MCP integration" }, { "name": "Knowledge Base", "description": "Natural language Q&A about HefestoAI" } ], "x-llms-txt": "https://hefestoai.narapallc.com/llms.txt", "x-agent-json": "https://hefestoai.narapallc.com/.well-known/agent.json" }