{
  "openapi": "3.1.0",
  "info": {
    "title": "Salman Ahmad Portfolio & Agent API",
    "version": "1.0.0",
    "description": "Production REST API, RFC 9457 typed error model, and Model Context Protocol (MCP) tool interfaces for Salman Ahmad Portfolio (salmanahmad.tech).",
    "x-api-versioning": {
      "strategy": "url-path",
      "currentVersion": "v1",
      "supportedVersions": ["v1"],
      "policy": "Major breaking changes result in an incremented URL path (/v1 -> /v2). Non-breaking additions are backward-compatible."
    },
    "x-deprecation-policy": {
      "notificationPeriodDays": 180,
      "headers": ["Deprecation", "Sunset", "Link"],
      "timeline": "Deprecated endpoints remain operational with Deprecation and Sunset headers for at least 180 days prior to retirement."
    },
    "contact": {
      "name": "Salman Ahmad",
      "email": "xheikhsalman4422@gmail.com",
      "url": "https://salmanahmad.tech"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://salmanahmad.tech",
      "description": "Production Edge Server"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/v1/contact": {
      "post": {
        "summary": "Send Contact Message",
        "description": "Submits a verified transmission or inquiry to Salman Ahmad with full delivery verification.",
        "operationId": "sendContactMessage",
        "tags": ["Transmissions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactTransmissionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transmission accepted and dispatched successfully",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactTransmissionResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/400BadRequest" },
          "429": { "$ref": "#/components/responses/429TooManyRequests" },
          "500": { "$ref": "#/components/responses/500InternalServerError" }
        }
      }
    },
    "/api/v1/skills": {
      "get": {
        "summary": "Retrieve Skills Matrix",
        "description": "Returns structured technical capabilities categorized across Languages, Frontend, Backend, Databases, and Cloud & Tools.",
        "operationId": "getSkillsMatrix",
        "tags": ["Portfolio Data"],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional category filter: Languages, Frontend, Backend, Databases, Cloud & Tools",
            "schema": {
              "type": "string",
              "enum": ["Languages", "Frontend", "Backend", "Databases", "Cloud & Tools"]
            },
            "example": "Backend"
          }
        ],
        "responses": {
          "200": {
            "description": "Categorized skill matrix retrieved successfully",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SkillGroup"
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/400BadRequest" },
          "429": { "$ref": "#/components/responses/429TooManyRequests" }
        }
      }
    },
    "/api/v1/projects": {
      "get": {
        "summary": "Retrieve Software Projects Catalog",
        "description": "Returns verified software applications, bots, dashboards, and AI tools with tech stacks, repository links, and descriptions.",
        "operationId": "getProjectsCatalog",
        "tags": ["Portfolio Data"],
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "Search keyword matching title, description, or technology",
            "schema": {
              "type": "string"
            },
            "example": "whatsapp"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of projects to return",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            },
            "example": 10
          }
        ],
        "responses": {
          "200": {
            "description": "Software project catalog retrieved successfully",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProjectItem"
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/429TooManyRequests" }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "Service Health Status",
        "description": "Returns operational uptime, health check status, and primary discovery endpoints.",
        "operationId": "getHealthStatus",
        "tags": ["System"],
        "responses": {
          "200": {
            "description": "Service is operational and healthy",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatusResponse"
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/429TooManyRequests" }
        }
      }
    },
    "/api/v1/mcp": {
      "get": {
        "summary": "MCP Server Discovery & SSE Handshake",
        "description": "Establishes a live Server-Sent Events (SSE) stream or returns discovery metadata for Model Context Protocol (MCP) clients.",
        "operationId": "getMcpDiscovery",
        "tags": ["Model Context Protocol"],
        "responses": {
          "200": {
            "description": "Server discovery metadata or SSE stream",
            "headers": {
              "Mcp-Session-Id": { "$ref": "#/components/headers/Mcp-Session-Id" },
              "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpDiscoveryResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Continuous SSE stream with endpoint and ping events"
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/429TooManyRequests" }
        }
      },
      "post": {
        "summary": "MCP JSON-RPC Tool & Resource Execution",
        "description": "Executes standard Model Context Protocol (MCP) JSON-RPC 2.0 requests, including initialize, tools/list, tools/call, resources/list, resources/read, prompts/list.",
        "operationId": "executeMcpJsonRpc",
        "tags": ["Model Context Protocol"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpJsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 execution result",
            "headers": {
              "Mcp-Session-Id": { "$ref": "#/components/headers/Mcp-Session-Id" },
              "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/400BadRequest" },
          "429": { "$ref": "#/components/responses/429TooManyRequests" },
          "500": { "$ref": "#/components/responses/500InternalServerError" }
        }
      }
    },
    "/api/contact": {
      "post": {
        "summary": "Legacy Contact Endpoint (Redirects to /api/v1/contact)",
        "description": "Maintained for backward compatibility. Relays to /api/v1/contact.",
        "operationId": "sendContactMessageLegacy",
        "tags": ["Transmissions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ContactTransmissionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactTransmissionResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/400BadRequest" },
          "429": { "$ref": "#/components/responses/429TooManyRequests" },
          "500": { "$ref": "#/components/responses/500InternalServerError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 Problem Details for HTTP APIs machine-readable error model",
        "required": ["type", "title", "status", "code", "message", "resolution"],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "URI identifier that categorizes the problem type",
            "example": "https://salmanahmad.tech/docs/errors#validation-error"
          },
          "title": {
            "type": "string",
            "description": "Short, human-readable summary of problem",
            "example": "Validation Error"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 400
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code for programmatic agent handling",
            "example": "VALIDATION_ERROR"
          },
          "message": {
            "type": "string",
            "description": "Detailed explanation of the error condition",
            "example": "Missing required fields: username, email, and contact_message are required."
          },
          "resolution": {
            "type": "string",
            "description": "Actionable resolution guidance telling the agent how to fix the error",
            "example": "Supply username, email, and contact_message conforming to /openapi.json."
          },
          "instance": {
            "type": "string",
            "description": "URI reference identifying this occurrence",
            "example": "/api/v1/contact"
          },
          "invalidParams": {
            "type": "array",
            "description": "List of specific parameter validation failures",
            "items": {
              "type": "object",
              "required": ["name", "reason"],
              "properties": {
                "name": { "type": "string", "example": "email" },
                "reason": { "type": "string", "example": "Must be a valid email address" }
              }
            }
          },
          "availableEndpoints": {
            "type": "array",
            "description": "List of valid API endpoints when encountering 404",
            "items": { "type": "string" }
          }
        }
      },
      "ContactTransmissionRequest": {
        "type": "object",
        "required": ["username", "email", "contact_message"],
        "properties": {
          "username": {
            "type": "string",
            "description": "Sender full name or corporate organization",
            "example": "Jane Doe"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Return email address for replies",
            "example": "jane@example.com"
          },
          "subject": {
            "type": "string",
            "description": "Inquiry subject line or project scope",
            "example": "Full-Stack Web App Development Proposal"
          },
          "contact_message": {
            "type": "string",
            "description": "Detailed proposal, project specifications, or message body",
            "example": "Hello Salman, we would like to collaborate on an agentic web platform."
          }
        }
      },
      "ContactTransmissionResponse": {
        "type": "object",
        "required": ["status", "message", "timestamp"],
        "properties": {
          "status": { "type": "string", "example": "transmitted" },
          "message": { "type": "string", "example": "Email sent successfully" },
          "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-03T06:00:00.000Z" },
          "details": {
            "type": "object",
            "properties": {
              "recipient": { "type": "string", "example": "Salman Ahmad (ahmmikun)" },
              "expectedResponse": { "type": "string", "example": "Within 24-48 business hours" }
            }
          }
        }
      },
      "SkillGroup": {
        "type": "object",
        "required": ["category", "skills"],
        "properties": {
          "category": {
            "type": "string",
            "description": "Category domain name",
            "example": "Languages"
          },
          "skills": {
            "type": "array",
            "description": "List of proficiencies within category",
            "items": { "type": "string" },
            "example": ["TypeScript", "JavaScript", "Python", "C++"]
          }
        }
      },
      "ProjectItem": {
        "type": "object",
        "required": ["id", "title", "subtitle", "description", "link", "tech"],
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "title": { "type": "string", "example": "XLICON V4 MD" },
          "subtitle": { "type": "string", "example": "WhatsApp Automation Bot" },
          "description": { "type": "string", "example": "Advanced WhatsApp bot built with Node.js and Baileys." },
          "link": { "type": "string", "format": "uri", "example": "https://github.com/ahmmikun/XLICON-V4-MD" },
          "tech": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Node.js", "Baileys", "MongoDB", "JavaScript"]
          }
        }
      },
      "HealthStatusResponse": {
        "type": "object",
        "required": ["status", "service", "version", "apiVersion", "canonical", "timestamp"],
        "properties": {
          "status": { "type": "string", "example": "healthy" },
          "service": { "type": "string", "example": "salmanahmad-portfolio" },
          "version": { "type": "string", "example": "1.0.0" },
          "apiVersion": { "type": "string", "example": "v1" },
          "canonical": { "type": "string", "format": "uri", "example": "https://salmanahmad.tech" },
          "timestamp": { "type": "string", "format": "date-time" },
          "uptimeSeconds": { "type": "integer", "example": 3600 },
          "endpoints": { "type": "object" }
        }
      },
      "McpDiscoveryResponse": {
        "type": "object",
        "required": ["name", "version", "protocolVersion", "endpoints", "capabilities"],
        "properties": {
          "name": { "type": "string", "example": "salmanahmad-portfolio-mcp" },
          "version": { "type": "string", "example": "1.0.0" },
          "protocolVersion": { "type": "string", "example": "2024-11-05" },
          "description": { "type": "string" },
          "endpoints": {
            "type": "object",
            "properties": {
              "streamableHttp": { "type": "string" },
              "sse": { "type": "string" },
              "v1": { "type": "string" },
              "manifest": { "type": "string" }
            }
          },
          "capabilities": { "type": "object" },
          "toolsCount": { "type": "integer", "example": 5 },
          "resourcesCount": { "type": "integer", "example": 4 }
        }
      },
      "McpJsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"], "example": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }], "example": 1 },
          "method": { "type": "string", "example": "tools/call" },
          "params": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "example": "get_portfolio_summary" },
              "arguments": { "type": "object" },
              "protocolVersion": { "type": "string", "example": "2024-11-05" }
            }
          }
        }
      },
      "McpJsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"], "example": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }] },
          "result": { "type": "object" },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" },
              "data": { "type": "object" }
            }
          }
        }
      }
    },
    "responses": {
      "400BadRequest": {
        "description": "Validation or bad request error formatted as RFC 9457 Problem Details",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "404NotFound": {
        "description": "Requested resource or endpoint does not exist",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "405MethodNotAllowed": {
        "description": "HTTP method not supported for target resource",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "429TooManyRequests": {
        "description": "Rate limit exceeded threshold of 60 req/min",
        "headers": {
          "Retry-After": { "$ref": "#/components/headers/Retry-After" },
          "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
        },
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "500InternalServerError": {
        "description": "Internal server or external service dispatch failure",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "description": "Max requests allowed in sliding window",
        "schema": { "type": "string", "example": "60" }
      },
      "RateLimit-Remaining": {
        "description": "Remaining request allowance in current window",
        "schema": { "type": "string", "example": "59" }
      },
      "RateLimit-Reset": {
        "description": "Seconds until rate limit window resets",
        "schema": { "type": "string", "example": "60" }
      },
      "RateLimit-Policy": {
        "description": "Rate limit policy directive (e.g. 60;w=60)",
        "schema": { "type": "string", "example": "60;w=60" }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying throttled request",
        "schema": { "type": "string", "example": "60" }
      },
      "Mcp-Session-Id": {
        "description": "Unique session identifier for MCP streamable connection",
        "schema": { "type": "string", "example": "mcp-session-1735689600" }
      },
      "X-API-Version": {
        "description": "API major and semantic version",
        "schema": { "type": "string", "example": "1.0.0" }
      }
    }
  }
}