{
  "openapi": "3.0.3",
  "info": {
    "title": "Alp Yalay Portfolio & Developer API",
    "version": "1.0.0",
    "description": "Public REST and MCP API for Alp Yalay's portfolio (alpyalay.org). Designed for AI agents, developers, and autonomous systems to retrieve project catalogs, bio, case studies, and skills programmatically.",
    "contact": {
      "name": "Alp Yalay",
      "email": "alpyalay@gmail.com",
      "url": "https://alpyalay.org/contact"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "x-versioning-policy": "URI path versioning (/v1/). Backward-incompatible changes increment major version. Deprecation signaled via RFC Sunset and Deprecation headers with a 180-day grace period.",
    "x-rate-limit": "Unthrottled. Endpoints serve static data and are safe to poll; no rate-limit headers are sent."
  },
  "servers": [
    {
      "url": "https://alpyalay.org",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "V1 Health Check",
        "description": "Returns API health status, version, server timestamp, and links to documentation and OpenAPI specification.",
        "operationId": "getHealthV1",
        "tags": ["System"],
        "responses": {
          "200": {
            "description": "API is healthy and operational.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/profile": {
      "get": {
        "summary": "Get Alp Yalay Profile",
        "description": "Returns full professional profile, roles, bio, location, contact methods, focus areas, key projects, and developer resource links.",
        "operationId": "getProfileV1",
        "tags": ["Profile"],
        "responses": {
          "200": {
            "description": "Profile details retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects": {
      "get": {
        "summary": "List Portfolio Projects",
        "description": "Returns a filtered or complete list of Alp Yalay's portfolio projects, apps, tools, and localization case studies.",
        "operationId": "listProjectsV1",
        "tags": ["Projects"],
        "parameters": [
          {
            "name": "lane",
            "in": "query",
            "required": false,
            "description": "Filter by project lane category",
            "schema": {
              "type": "string",
              "enum": ["builder", "client", "localization", "ai-tools"]
            }
          },
          {
            "name": "tier",
            "in": "query",
            "required": false,
            "description": "Filter by project tier",
            "schema": {
              "type": "string",
              "enum": ["featured", "supporting", "archive"]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search keyword in project slug, title, or summary",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching portfolio projects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects/{slug}": {
      "get": {
        "summary": "Get Single Project or Case Study",
        "description": "Returns detailed information, proof points, links, and case study metadata for a specific project slug.",
        "operationId": "getProjectBySlugV1",
        "tags": ["Projects"],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Project or case study slug (e.g. 'realdex', 'battle-talent', 'heroes-of-hammerwatch-2', 'sim-racing-survey', 'vibe-coding-ecosystem')",
            "schema": {
              "type": "string",
              "example": "realdex"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Project details retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectDetailResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid slug format.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Project not found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/skills": {
      "get": {
        "summary": "List Skills and Domains",
        "description": "Returns comprehensive technical skills, languages, certifications, and core specialization domains.",
        "operationId": "listSkillsV1",
        "tags": ["Skills"],
        "responses": {
          "200": {
            "description": "Skills and competencies retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillsResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Legacy Health Check",
        "description": "Returns API health status and timestamp.",
        "operationId": "getHealthLegacy",
        "tags": ["System"],
        "responses": {
          "200": {
            "description": "API is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "summary": "MCP Server Info",
        "description": "Describes the Model Context Protocol (MCP) JSON-RPC 2.0 endpoint capabilities and available tools.",
        "operationId": "getMcpInfo",
        "tags": ["MCP"],
        "responses": {
          "200": {
            "description": "MCP endpoint description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpInfoResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "MCP JSON-RPC 2.0 Dispatcher",
        "description": "Dispatches MCP JSON-RPC 2.0 requests: `initialize`, `tools/list`, `tools/call`, `ping`. Tools available: `get_portfolio_info`, `list_projects`, `get_case_study`.",
        "operationId": "callMcp",
        "tags": ["MCP"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 result or method error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON (-32700) or Invalid Request (-32600).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 Problem Details object for HTTP APIs",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference that identifies the problem type.",
            "example": "https://alpyalay.org/errors/project_not_found"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type.",
            "example": "Project Not Found"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code generated by the origin server.",
            "example": 404
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence.",
            "example": "No project exists with slug 'unknown'."
          },
          "code": {
            "type": "string",
            "description": "A machine-readable error code.",
            "example": "PROJECT_NOT_FOUND"
          },
          "instance": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference that identifies the specific occurrence.",
            "example": "/api/v1/projects/unknown"
          }
        },
        "required": ["type", "title", "status", "detail", "code"]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "service": {
            "type": "string",
            "example": "alpyalay-portfolio-api"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-22T12:00:00.000Z"
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "example": "https://alpyalay.org/developers"
          },
          "openapi": {
            "type": "string",
            "format": "uri",
            "example": "https://alpyalay.org/openapi.json"
          }
        },
        "required": ["status", "timestamp"]
      },
      "ProfileResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Alp Yalay"
          },
          "alternateNames": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Alp", "KhazP"]
          },
          "title": {
            "type": "string",
            "example": "Technical Producer & Full-Stack Engineer"
          },
          "roles": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Technical Producer", "Full-Stack Web Engineer", "Game Localization Specialist"]
          },
          "bio": {
            "type": "string",
            "example": "Products, websites, and experiments."
          },
          "detail": {
            "type": "string",
            "example": "Personal builds stay in front. Client work, archive pieces, and older tools continue in the full index."
          },
          "location": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "example": "Istanbul" },
              "country": { "type": "string", "example": "Turkey" },
              "timezone": { "type": "string", "example": "UTC+3" }
            },
            "required": ["city", "country", "timezone"]
          },
          "contact": {
            "type": "object",
            "properties": {
              "email": { "type": "string", "example": "alpyalay@gmail.com" },
              "website": { "type": "string", "example": "https://alpyalay.org" },
              "github": { "type": "string", "example": "https://github.com/KhazP" },
              "linkedin": { "type": "string", "example": "https://www.linkedin.com/in/alp-yalay/" },
              "x": { "type": "string", "example": "https://x.com/alpyalay" }
            },
            "required": ["email", "website", "github"]
          },
          "focusAreas": {
            "type": "array",
            "items": { "type": "string" }
          },
          "keyProjects": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "name": { "type": "string" },
                "description": { "type": "string" },
                "url": { "type": "string" }
              },
              "required": ["slug", "name", "description", "url"]
            }
          },
          "developerResources": {
            "type": "object",
            "properties": {
              "portal": { "type": "string" },
              "openapi": { "type": "string" },
              "llms": { "type": "string" },
              "mcp": { "type": "string" },
              "cli": { "type": "string" }
            },
            "required": ["portal", "openapi", "llms", "mcp"]
          }
        },
        "required": ["name", "title", "roles", "bio", "location", "contact", "developerResources"]
      },
      "Project": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "example": "realdex" },
          "title": { "type": "string", "example": "RealDex" },
          "titleTr": { "type": "string", "example": "RealDex" },
          "lane": { "type": "string", "enum": ["builder", "client", "localization", "ai-tools"], "example": "builder" },
          "tier": { "type": "string", "enum": ["featured", "supporting", "archive"], "example": "featured" },
          "role": { "type": "string", "example": "Lead Engineer & Designer" },
          "status": { "type": "string", "example": "Shipped (iOS & Android)" },
          "badge": { "type": "string", "nullable": true, "example": "On-Device AI" },
          "summary": { "type": "string", "example": "AI-powered wildlife collection mobile app using dual on-device models." },
          "summaryTr": { "type": "string", "example": "Cihaz üzerinde çalışan çift yapay zekâ modeliyle vahşi yaşam koleksiyon uygulaması." },
          "proofPoints": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["10,000+ species recognized offline", "30fps real-time YOLO detection"]
          },
          "links": {
            "type": "object",
            "properties": {
              "live": { "type": "string" },
              "github": { "type": "string" },
              "caseStudy": { "type": "string" },
              "appStore": { "type": "string" },
              "playStore": { "type": "string" }
            }
          }
        },
        "required": ["slug", "title", "lane", "tier", "summary", "links"]
      },
      "ProjectListResponse": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "example": 19 },
          "projects": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Project" }
          }
        },
        "required": ["total", "projects"]
      },
      "ProjectDetailResponse": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "example": "realdex" },
          "title": { "type": "string", "example": "RealDex" },
          "titleTr": { "type": "string", "nullable": true },
          "lane": { "type": "string" },
          "tier": { "type": "string" },
          "role": { "type": "string", "nullable": true },
          "status": { "type": "string", "nullable": true },
          "summary": { "type": "string", "nullable": true },
          "summaryTr": { "type": "string", "nullable": true },
          "proofPoints": {
            "type": "array",
            "items": { "type": "string" }
          },
          "links": { "type": "object" },
          "caseStudy": {
            "type": "object",
            "nullable": true,
            "properties": {
              "title": { "type": "string" },
              "category": { "type": "string" },
              "date": { "type": "string" },
              "excerpt": { "type": "string" },
              "url": { "type": "string" }
            }
          }
        },
        "required": ["slug", "title", "lane", "tier", "links"]
      },
      "SkillsResponse": {
        "type": "object",
        "properties": {
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string", "example": "Frontend" },
                "items": {
                  "type": "array",
                  "items": { "type": "string" },
                  "example": ["Next.js", "React", "TypeScript", "Tailwind CSS"]
                }
              },
              "required": ["title", "items"]
            }
          },
          "languages": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Turkish — Native", "English — Professional working proficiency"]
          },
          "certifications": {
            "type": "array",
            "items": { "type": "string" }
          },
          "domains": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["skills", "languages", "certifications", "domains"]
      },
      "McpInfoResponse": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "alpyalay-portfolio" },
          "version": { "type": "string", "example": "1.0.0" },
          "description": { "type": "string" },
          "tools": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["get_portfolio_info", "list_projects", "get_case_study"]
          }
        },
        "required": ["name", "version", "description", "tools"]
      },
      "JsonRpcRequest": {
        "type": "object",
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"], "example": "2.0" },
          "id": {
            "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }],
            "example": 1
          },
          "method": {
            "type": "string",
            "enum": ["initialize", "tools/list", "tools/call", "ping"],
            "example": "tools/call"
          },
          "params": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "enum": ["get_portfolio_info", "list_projects", "get_case_study"],
                "example": "get_case_study"
              },
              "arguments": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "enum": ["battle-talent", "heroes-of-hammerwatch-2", "realdex", "sim-racing-survey", "vibe-coding-ecosystem"],
                    "example": "realdex"
                  }
                }
              }
            }
          }
        },
        "required": ["jsonrpc", "method"]
      },
      "JsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"], "example": "2.0" },
          "id": {
            "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }],
            "example": 1
          },
          "result": { "type": "object", "description": "Method result payload." },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": -32601 },
              "message": { "type": "string", "example": "Method not found" }
            },
            "required": ["code", "message"]
          }
        },
        "required": ["jsonrpc", "id"]
      }
    }
  }
}