{ "openapi": "3.1.0", "info": { "title": "Mete Güneş Public API & Agent Services", "version": "1.0.0", "description": "Public API providing deterministic website SEO/GEO/AEO site audits, automation ROI calculations, Model Context Protocol (MCP) server endpoints, paginated solutions, async background jobs, and AI agent integration services by Mete Güneş.", "contact": { "name": "Mete Güneş", "url": "https://metegunes.io/developers", "email": "contact@metegunes.io" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "x-deprecation-policy": "https://metegunes.io/developers#deprecation", "x-sunset-date": "2027-11-11", "x-idempotency-policy": "Supported on all mutation and query operations via Idempotency-Key HTTP header.", "x-pagination-policy": "Cursor and page/limit pagination supported on list endpoints with standard metadata and link relations.", "x-async-job-policy": "Long-running tasks return 202 Accepted with Location header for status polling." }, "servers": [ { "url": "https://metegunes.io/api/v1", "description": "Production API v1" }, { "url": "https://metegunes.io/api/v1/sandbox", "description": "Sandbox & Safe Test Mode Environment (zero production mutation)" } ], "paths": { "/site-audit": { "get": { "summary": "Deterministic SEO, GEO, and AEO website audit", "description": "Evaluates a target public website URL against technical SEO, Generative Engine Optimization (GEO), and Answer Engine Optimization (AEO) deterministic rules.", "operationId": "runSiteAudit", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The public HTTP or HTTPS URL to audit.", "schema": { "type": "string", "format": "uri", "example": "https://example.com" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Audit completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAuditResponse" } } } }, "400": { "description": "Invalid or missing URL parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Target URL unprocessable or unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded (10 requests per 10-minute window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/roi-calc": { "get": { "summary": "Automation ROI and hours saved calculation", "description": "Calculates projected annual financial savings, break-even period, and operational efficiency gains from automating business workflows.", "operationId": "calculateRoi", "parameters": [ { "name": "monthlyExecutions", "in": "query", "required": true, "description": "Number of monthly task runs or transactions.", "schema": { "type": "number", "default": 250000, "example": 250000 } }, { "name": "developerHourlyRate", "in": "query", "required": false, "description": "Hourly cost in USD for engineering or manual operations.", "schema": { "type": "number", "default": 65, "example": 65 } }, { "name": "serverHostingCost", "in": "query", "required": false, "description": "Estimated monthly hosting and cloud infrastructure cost in USD.", "schema": { "type": "number", "default": 40, "example": 40 } }, { "name": "dataComplexity", "in": "query", "required": false, "description": "Complexity tier: 1 (basic), 2 (intermediate), 3 (advanced multi-system).", "schema": { "type": "integer", "minimum": 1, "maximum": 3, "default": 2, "example": 2 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "ROI calculation completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoiCalculationResponse" } } } }, "400": { "description": "Invalid parameters supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal calculation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/solutions": { "get": { "summary": "List production AI workflow solutions (Paginated)", "description": "Retrieves a paginated list of enterprise AI automation architectures, lead routing systems, and RAG knowledge base solutions.", "operationId": "listSolutions", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number (1-based index).", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of solution records to return per page.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor for cursor-based navigation.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Paginated solutions list retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSolutionsResponse" } } } }, "400": { "description": "Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs": { "post": { "summary": "Submit asynchronous background job", "description": "Submits a long-running site analysis or workflow job for background execution. Conforms to the REST async-job 202 Accepted pattern.", "operationId": "createAsyncJob", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "target" ], "properties": { "type": { "type": "string", "enum": [ "deep_audit", "benchmark_eval" ], "example": "deep_audit" }, "target": { "type": "string", "format": "uri", "example": "https://example.com" } } } } } }, "responses": { "202": { "description": "Job accepted for background execution", "headers": { "Location": { "description": "Relative or absolute URL where the client can poll for task execution status.", "schema": { "type": "string", "example": "https://metegunes.io/api/v1/jobs/job_17910123" } }, "Retry-After": { "description": "Recommended polling interval in seconds.", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "description": "Invalid job parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs/{job_id}": { "get": { "summary": "Poll asynchronous job execution status", "description": "Retrieves current execution state and results for an asynchronous background job.", "operationId": "getJobStatus", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Unique identifier of the asynchronous job.", "schema": { "type": "string", "example": "job_17910123" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Job status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobStatus" } } } }, "404": { "description": "Job ID not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch": { "post": { "summary": "Execute batch array of operations", "description": "Executes an array of REST operations in a single atomic request, allowing agents to perform bulk tasks without looping individual HTTP calls.", "operationId": "executeBatch", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "JSON array or object containing list of operations to execute in batch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "description": "List of operations to execute in batch", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "op_1" }, "method": { "type": "string", "enum": [ "GET", "POST" ], "example": "GET" }, "path": { "type": "string", "example": "/api/v1/site-audit?url=https://example.com" }, "body": { "type": "object" } }, "required": [ "method", "path" ] } } }, "required": [ "operations" ] } } } }, "responses": { "200": { "description": "Batch operations completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "total": { "type": "integer", "example": 2 }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "path": { "type": "string" }, "result": { "type": "object" } } } } } } } } }, "400": { "description": "Invalid batch request format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mcp": { "post": { "summary": "Model Context Protocol (MCP) JSON-RPC 2.0 Handler", "description": "Executes MCP JSON-RPC 2.0 requests including initialize, notifications/initialized, ping, tools/list, and tools/call.", "operationId": "mcpRpcHandler", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Standard JSON-RPC 2.0 payload containing id, method, and params.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC response or notification acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcResponse" } } } }, "400": { "description": "Invalid JSON or missing parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcResponse" } } } }, "404": { "description": "Tool or method not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "summary": "MCP Capabilities or SSE Stream Handshake", "description": "Returns MCP server metadata, capability declaration, and tools list in JSON; or initiates SSE text/event-stream handshake when requested.", "operationId": "mcpCapabilitiesHandler", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "MCP server capabilities or SSE endpoint declaration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpCapabilitiesResponse" } }, "text/event-stream": { "schema": { "type": "string", "example": "event: endpoint\ndata: https://metegunes.io/api/v1/mcp\n\n" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/legacy/site-audit": { "get": { "summary": "Legacy Unversioned Site Audit (Deprecated)", "description": "Deprecated legacy endpoint. Please migrate to /api/v1/site-audit.", "deprecated": true, "operationId": "legacySiteAudit", "x-sunset": "2027-11-11", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audit result with deprecation notice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAuditResponse" } } } } } } } }, "components": { "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique UUID or token to prevent duplicate request execution and guarantee idempotent retries per IETF draft-ietf-httpapi-idempotency-key-header.", "schema": { "type": "string", "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "status" ], "properties": { "code": { "type": "string", "example": "NOT_FOUND", "description": "Machine-readable uppercase error identifier." }, "message": { "type": "string", "example": "The requested API endpoint was not found.", "description": "Human-readable error explanation." }, "status": { "type": "integer", "example": 404, "description": "HTTP status code matching the response status." } } } } }, "SiteAuditResponse": { "type": "object", "required": [ "schema_version", "audited_at", "url", "scores", "facts", "checks" ], "properties": { "schema_version": { "type": "string", "example": "metegunes_public_audit/v1" }, "audited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "scores": { "type": "object", "required": [ "seo", "geo", "aeo" ], "properties": { "seo": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Technical SEO score (0-100)" }, "geo": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Generative Engine Optimization score (0-100)" }, "aeo": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Answer Engine Optimization score (0-100)" } } }, "facts": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonical": { "type": "string" }, "h1Count": { "type": "integer" }, "h2Count": { "type": "integer" }, "jsonLdCount": { "type": "integer" }, "wordCount": { "type": "integer" }, "images": { "type": "integer" }, "missingAlt": { "type": "integer" }, "internalLinks": { "type": "integer" } } }, "checks": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "status", "detail", "weight" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "detail": { "type": "string" }, "weight": { "type": "number" } } } }, "limits": { "type": "array", "items": { "type": "string" } } } }, "RoiCalculationResponse": { "type": "object", "required": [ "schema_version", "calculated_at", "inputs", "results", "currency" ], "properties": { "schema_version": { "type": "string", "example": "metegunes_roi_calculator/v1" }, "calculated_at": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "properties": { "monthlyExecutions": { "type": "number" }, "developerHourlyRate": { "type": "number" }, "serverHostingCost": { "type": "number" }, "dataComplexity": { "type": "integer" } } }, "results": { "type": "object", "properties": { "makeMonthlyCost": { "type": "number" }, "customMonthlyCost": { "type": "number" }, "monthlySavings": { "type": "number" }, "annualSavings": { "type": "number" }, "oneTimeSetupCost": { "type": "number" }, "paybackPeriodMonths": { "type": "number" }, "roiPercentage": { "type": "number" } } }, "currency": { "type": "string", "example": "USD" } } }, "SolutionItem": { "type": "object", "required": [ "id", "title", "url" ], "properties": { "id": { "type": "string", "example": "ai-workflow-automation" }, "title": { "type": "string", "example": "AI İş Akışı Otomasyonu" }, "url": { "type": "string", "format": "uri", "example": "https://metegunes.io/solutions/ai-workflow-automation" } } }, "PaginationMetadata": { "type": "object", "required": [ "total", "page", "limit", "has_next_page" ], "properties": { "total": { "type": "integer", "example": 5 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "has_next_page": { "type": "boolean", "example": false }, "next_cursor": { "type": [ "string", "null" ], "example": null } } }, "PaginationLinks": { "type": "object", "required": [ "self" ], "properties": { "self": { "type": "string", "example": "https://metegunes.io/api/v1/solutions?page=1&limit=20" }, "next": { "type": [ "string", "null" ], "example": null }, "prev": { "type": [ "string", "null" ], "example": null } } }, "PaginatedSolutionsResponse": { "type": "object", "required": [ "items", "pagination", "links" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SolutionItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "AsyncJobAccepted": { "type": "object", "required": [ "job_id", "status", "created_at", "poll_url", "retry_after" ], "properties": { "job_id": { "type": "string", "example": "job_17910123" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed" ], "example": "pending" }, "created_at": { "type": "string", "format": "date-time" }, "poll_url": { "type": "string", "format": "uri", "example": "https://metegunes.io/api/v1/jobs/job_17910123" }, "retry_after": { "type": "integer", "example": 5 }, "message": { "type": "string", "example": "Async background task accepted for execution." } } }, "AsyncJobStatus": { "type": "object", "required": [ "job_id", "status", "completed_at", "result" ], "properties": { "job_id": { "type": "string", "example": "job_17910123" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "example": "completed" }, "completed_at": { "type": "string", "format": "date-time" }, "result": { "type": "object" } } }, "McpJsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "number", "null" ] }, "method": { "type": "string", "enum": [ "initialize", "notifications/initialized", "ping", "tools/list", "tools/call" ] }, "params": { "type": "object" } } }, "McpJsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object" } } } } }, "McpCapabilitiesResponse": { "type": "object", "required": [ "name", "version", "protocolVersion", "capabilities", "serverInfo", "tools" ], "properties": { "name": { "type": "string", "example": "metegunes-io-mcp" }, "version": { "type": "string", "example": "1.0.0" }, "protocolVersion": { "type": "string", "example": "2024-11-05" }, "description": { "type": "string" }, "capabilities": { "type": "object", "properties": { "tools": { "type": "object" }, "resources": { "type": "object" }, "prompts": { "type": "object" }, "logging": { "type": "object" } } }, "serverInfo": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "tools": { "type": "array", "items": { "type": "object" } } } } } } }