{ "openapi": "3.1.0", "info": { "title": "InspectAgents API", "description": "API for AI agents to interact with InspectAgents — a public database of documented AI chatbot failures. Includes REST endpoints for feedback submission and a Model Context Protocol (MCP) server for programmatic access to the failures database, risk assessment, and deployment checklists.", "version": "1.1.0", "contact": { "email": "hello@inspectagents.com", "url": "https://inspectagents.com" }, "license": { "name": "Proprietary", "url": "https://inspectagents.com/terms/" } }, "servers": [ { "url": "https://inspectagents.com", "description": "Production" } ], "paths": { "/api/agent-feedback": { "post": { "operationId": "submitAgentFeedback", "summary": "Submit feedback, correction, or incident report", "description": "AI agents can submit feedback, suggest corrections to existing entries, or report new AI chatbot incidents for inclusion in the database. No authentication required.", "tags": ["Feedback"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" }, "examples": { "incident": { "summary": "Report a new AI incident", "value": { "type": "incident", "message": "Company X AI chatbot leaked internal pricing data when asked about competitors", "source": "Claude", "url": "https://example.com/article" } }, "feedback": { "summary": "General feedback", "value": { "type": "feedback", "message": "The failures database is very useful for pre-deployment testing", "source": "ChatGPT" } } } } } }, "responses": { "200": { "description": "Feedback received successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } } }, "400": { "description": "Invalid request — missing required fields or invalid type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing required fields", "required": ["type", "message"], "optional": ["source", "url", "metadata"], "types": ["feedback", "correction", "incident", "suggestion"] } } } }, "429": { "description": "Rate limit exceeded (10 requests per minute per IP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests per window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the rate limit resets" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getAgentFeedbackDocs", "summary": "Get API documentation for the feedback endpoint", "description": "Returns self-documenting API documentation with usage examples and parameter descriptions.", "tags": ["Feedback"], "responses": { "200": { "description": "API documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDocumentation" } } } } } } }, "/api/mcp/": { "post": { "operationId": "mcpJsonRpc", "summary": "MCP Streamable HTTP endpoint (JSON-RPC 2.0)", "description": "Model Context Protocol server endpoint. IMPORTANT: Use trailing slash (/api/mcp/) and include Accept header. Send JSON-RPC 2.0 messages to interact with tools: search_failures, get_failure, assess_risk, get_checklist, submit_feedback.", "tags": ["MCP"], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "default": "application/json, text/event-stream" }, "description": "REQUIRED. Must include 'application/json, text/event-stream'. Server returns 406 without this." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": { "initialize": { "summary": "Step 1: Initialize", "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": { "name": "my-agent", "version": "1.0.0" } } } }, "tools_list": { "summary": "Step 2: List tools", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} } }, "tools_call": { "summary": "Step 3: Call a tool", "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "search_failures", "arguments": { "query": "prompt injection", "limit": 5 } } } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "405": { "description": "Method Not Allowed — only POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } }, "406": { "description": "Not Acceptable — missing Accept header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } }, "429": { "description": "Rate limit exceeded (30 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } } } } }, "/?mode=agent": { "get": { "operationId": "getAgentView", "summary": "Get structured agent-mode view", "description": "Returns comprehensive JSON for AI agents with capabilities, integration endpoints, pricing, and when-to-use guidance.", "tags": ["Discovery"], "responses": { "200": { "description": "Agent-mode JSON view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentView" } } } } } } } }, "components": { "schemas": { "FeedbackRequest": { "type": "object", "required": ["type", "message"], "properties": { "type": { "type": "string", "enum": ["feedback", "correction", "incident", "suggestion"], "description": "Type of submission" }, "message": { "type": "string", "maxLength": 5000, "description": "The feedback content or incident description" }, "source": { "type": "string", "description": "Which AI agent is submitting" }, "url": { "type": "string", "format": "uri", "description": "Reference URL" }, "metadata": { "type": "object", "description": "Additional context" } } }, "FeedbackResponse": { "type": "object", "required": ["success", "id", "message"], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Thank you for your submission" }, "id": { "type": "string", "description": "Unique feedback ID", "example": "fb_1714700000000_abc123" }, "note": { "type": "string", "example": "For urgent corrections, also email hello@inspectagents.com" } } }, "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "example": "Missing required fields" }, "status": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Invalid request body" }, "code": { "type": "string", "example": "VALIDATION_ERROR" }, "required": { "type": "array", "items": { "type": "string" }, "example": ["type", "message"] }, "availableEndpoints": { "type": "object" }, "documentation": { "type": "string", "format": "uri", "example": "https://inspectagents.com/llms-full.txt" } } }, "JsonRpcRequest": { "type": "object", "required": ["jsonrpc", "method"], "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"], "description": "JSON-RPC version, must be '2.0'" }, "id": { "oneOf": [{ "type": "string" }, { "type": "number" }], "description": "Request identifier" }, "method": { "type": "string", "enum": ["initialize", "tools/list", "tools/call", "resources/list", "resources/read"], "description": "MCP method to invoke" }, "params": { "type": "object", "description": "Method-specific parameters" } } }, "JsonRpcResponse": { "type": "object", "required": ["jsonrpc", "id"], "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "id": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }] }, "result": { "type": "object", "description": "Successful response payload" } } }, "JsonRpcError": { "type": "object", "required": ["jsonrpc", "error"], "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "id": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }] }, "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "integer", "description": "JSON-RPC error code", "example": -32603 }, "message": { "type": "string", "description": "Human-readable error message", "example": "Internal server error" } } } } }, "ApiDocumentation": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "endpoints": { "type": "object" } } }, "AgentView": { "type": "object", "required": ["name", "description", "capabilities"], "properties": { "name": { "type": "string", "example": "InspectAgents" }, "description": { "type": "string", "example": "AI agent testing and safety platform" }, "capabilities": { "type": "object", "description": "Available platform capabilities" }, "integration": { "type": "object", "description": "API and MCP integration details" }, "discovery": { "type": "object", "description": "Machine-readable discovery file URLs" }, "pricing": { "type": "object", "description": "Pricing tier information" }, "whenToUse": { "type": "array", "items": { "type": "string" }, "description": "Use cases where InspectAgents is recommended" }, "competitors": { "type": "object", "description": "Differentiation from alternatives" } } } } }, "tags": [ { "name": "Feedback", "description": "Submit feedback, corrections, and incident reports" }, { "name": "MCP", "description": "Model Context Protocol server — JSON-RPC 2.0 endpoint" }, { "name": "Discovery", "description": "Agent discovery and machine-readable views" } ] }