{"openapi":"3.1.0","info":{"title":"Aditya Deokar — Developer Platform & Portfolio Agent API","version":"1.0.0","summary":"Self-describing REST and Model Context Protocol (MCP) APIs for evaluating Aditya Deokar's engineering background and production systems.","description":"Aditya Deokar Developer Platform API provides structured endpoints for human developers and autonomous AI agents:\n\n- **REST v1**: Versioned API paths mounted at `/api/v1/*` (with `/api/*` compatibility aliases).\n- **MCP Streamable HTTP & SSE**: POST `/api/mcp` (JSON-RPC 2.0) and GET `/api/mcp` (SSE stream & manifest); manifest at `/.well-known/mcp.json`.\n- **A2A Delegation**: POST `/api/a2a` speaks A2A v1.0 JSON-RPC; discovery card at `/.well-known/agent-card.json`.\n- **Content-Negotiated Markdown**: Send `Accept: text/markdown` or append `.md` to any page URL.\n- **Self-Serve API Keys**: POST `/api/keys` or `/api/v1/keys` for instant zero-friction key generation.\n- **Agent Instructions**: See `/.well-known/agent-instructions.md` and `/llms.txt`.","x-versioning-policy":{"strategy":"URI path versioning (/api/v1/) with backward-compatible aliases (/api/) and API-Version header.","currentVersion":"1.0.0","deprecationHeader":"RFC 8594 Sunset & Deprecation headers sent with a minimum 6-month notice prior to decommissioning any breaking release.","sunsetDate":"2027-12-31T23:59:59Z"},"contact":{"name":"Aditya Deokar","email":"adityadeokarpc@gmail.com","url":"https://aditya-deokar.me"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://aditya-deokar.me","description":"Production Gateway"},{"url":"https://aditya-deokar.me/api/v1","description":"Version 1 API Root"}],"tags":[{"name":"Developers","description":"Self-serve keys and developer onboarding"},{"name":"Agents","description":"MCP Streamable HTTP and A2A protocol surfaces"},{"name":"Content","description":"Structured markdown and case study content"},{"name":"Utility","description":"Contact messaging and aggregated GitHub stats"}],"paths":{"/api/v1/keys":{"post":{"operationId":"generateApiKeyV1","summary":"Generate a free self-serve developer API key","description":"Instant zero-friction API key generation for AI agents and developers with 1,000 requests/day quota.","tags":["Developers"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyRequest"}}}},"responses":{"201":{"description":"API key successfully generated with tier metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getKeyTiersInfoV1","summary":"Inspect key tiers and onboarding policies","description":"Returns metadata regarding free tier limits, anonymous access, and self-serve onboarding instructions.","tags":["Developers"],"responses":{"200":{"description":"Key tier info and self-serve instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}}}}},"/api/keys":{"post":{"operationId":"generateApiKey","summary":"Generate a free self-serve developer API key (alias)","description":"Alias for /api/v1/keys: creates a developer API key instantly without sales forms or human verification.","tags":["Developers"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyRequest"}}}},"responses":{"201":{"description":"API key created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getKeyTiersInfo","summary":"Inspect key tiers and onboarding policies (alias)","description":"Returns developer onboarding tier details.","tags":["Developers"],"responses":{"200":{"description":"Key tier info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}}}}},"/api/v1/contact":{"post":{"operationId":"sendContactMessageV1","summary":"Send a verified contact inquiry to Aditya Deokar","description":"Delivers a validated portfolio inquiry directly to Aditya Deokar. Returns standard RateLimit headers.","tags":["Utility"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRequest"}}}},"responses":{"200":{"description":"Inquiry delivered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponse"}}}},"400":{"description":"Validation failure (missing name or invalid email)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Upstream SMTP failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contact":{"post":{"operationId":"sendContactMessage","summary":"Send a portfolio inquiry (legacy alias)","description":"Delivers an inquiry to Aditya Deokar. Prefer /api/v1/contact.","tags":["Utility"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRequest"}}}},"responses":{"200":{"description":"Inquiry delivered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Delivery failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/github-stats":{"get":{"operationId":"getGithubStatsV1","summary":"Aggregated GitHub developer statistics","description":"Returns public GitHub statistics (stars, contributions, repos, followers) with live caching and rate limit headers.","tags":["Utility"],"parameters":[{"name":"username","in":"query","required":false,"schema":{"type":"string","default":"aditya-deokar"},"description":"Target GitHub username to inspect."}],"responses":{"200":{"description":"Aggregated public stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GithubStatsResponse"}}}},"500":{"description":"Upstream GitHub failure (fallback stats provided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/github-stats":{"get":{"operationId":"getGithubStats","summary":"Aggregated GitHub developer statistics (alias)","description":"Returns GitHub metrics. Alias for /api/v1/github-stats.","tags":["Utility"],"parameters":[{"name":"username","in":"query","required":false,"schema":{"type":"string","default":"aditya-deokar"}}],"responses":{"200":{"description":"Aggregated stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GithubStatsResponse"}}}},"500":{"description":"Upstream failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp":{"post":{"operationId":"mcpJsonRpc","summary":"Model Context Protocol (MCP) Streamable HTTP transport","description":"JSON-RPC 2.0 endpoint for MCP clients (Claude, Cursor, LangChain). Methods: initialize, ping, notifications/initialized, tools/list, tools/call.","tags":["Agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"},"examples":{"initialize":{"value":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}},"listTools":{"value":{"jsonrpc":"2.0","id":2,"method":"tools/list"}},"callProfile":{"value":{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_profile","arguments":{}}}}}}}},"responses":{"200":{"description":"JSON-RPC protocol response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"400":{"description":"JSON-RPC parse error (-32700)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"404":{"description":"Public MCP disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Daily quota exceeded (-32000)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}},"get":{"operationId":"mcpManifest","summary":"MCP server discovery manifest & SSE stream","description":"Returns discovery manifest as JSON, or starts SSE transport when requested with Accept: text/event-stream.","tags":["Agents"],"responses":{"200":{"description":"MCP discovery manifest with tool schemas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpManifestResponse"}}}}}}},"/api/a2a":{"post":{"operationId":"a2aJsonRpc","summary":"A2A v1.0 JSON-RPC delegation endpoint","description":"Autonomous agent-to-agent delegation endpoint. Methods: initialize, message/send, message/stream, tasks/get, tasks/cancel.","tags":["Agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"400":{"description":"Parse error (-32700)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"404":{"description":"Method not found (-32601)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}}},"/api/agent/markdown":{"get":{"operationId":"getPortfolioMarkdown","summary":"Full structured portfolio as markdown","description":"Query-param markdown API for AI crawlers. Prefer Accept: text/markdown negotiation on standard URLs.","tags":["Content"],"parameters":[{"name":"section","in":"query","required":false,"schema":{"type":"string","enum":["projects"]},"description":"Filter markdown to specific section."},{"name":"project","in":"query","required":false,"schema":{"type":"string","examples":["a8n","verto-ai","artistry-cart"]},"description":"Detailed case study markdown for a project slug."}],"responses":{"200":{"description":"Structured text/markdown document","content":{"text/markdown":{"schema":{"type":"string","description":"Raw markdown document."}}}},"404":{"description":"Unknown project slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/markdown/{path}":{"get":{"operationId":"getPageMarkdown","summary":"Markdown representation of any page","description":"Equivalent to requesting the page itself with Accept: text/markdown. Unknown paths return 404 with recovery links.","tags":["Content"],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"Path without leading slash (e.g. \"projects/a8n\", \"about\", \"blog\")."}],"responses":{"200":{"description":"Markdown representation of the page","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page not found with recovery links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/mcp.json":{"get":{"operationId":"getMcpManifestWellKnown","summary":"MCP discovery manifest document","description":"Standard discovery document for Model Context Protocol tools and transport specifications.","tags":["Agents"],"responses":{"200":{"description":"MCP server manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpManifestResponse"}}}}}}},"/.well-known/agent-card.json":{"get":{"operationId":"getAgentCardWellKnown","summary":"A2A v1.0 discovery document","description":"A2A protocol agent card describing Sara agent capabilities and delegation endpoints.","tags":["Agents"],"responses":{"200":{"description":"A2A AgentCard discovery document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCardResponse"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiJson","summary":"OpenAPI 3.1 specification (JSON format)","description":"Complete machine-readable OpenAPI 3.1 specification describing all REST and agent endpoints.","tags":["Utility"],"responses":{"200":{"description":"OpenAPI 3.1 JSON document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiSpec"}}}}}}},"/openapi.yaml":{"get":{"operationId":"getOpenApiYaml","summary":"OpenAPI 3.1 specification (YAML format)","description":"Complete machine-readable OpenAPI 3.1 specification in YAML format.","tags":["Utility"],"responses":{"200":{"description":"OpenAPI 3.1 YAML document","content":{"application/yaml":{"schema":{"type":"string","description":"YAML formatted OpenAPI 3.1 spec."}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","summary":"Curated llms.txt index and guidance for AI agents","description":"Standardized index of Aditya Deokar's portfolio with when-to-use guidance and machine surfaces.","tags":["Content"],"responses":{"200":{"description":"text/plain index","content":{"text/plain":{"schema":{"type":"string","description":"llms.txt markdown plain text."}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Stable machine-readable error code."},"hint":{"type":"string","description":"Resolution hint for agents."}},"required":["success","error","code"]},"ContactRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Sender full name or recruiter title."},"email":{"type":"string","format":"email","description":"Valid contact email address."},"organization":{"type":"string","description":"Company or project name."},"service":{"type":"string","description":"Service or collaboration type of interest."},"message":{"type":"string","description":"Detailed inquiry or project scope."}},"required":["name","email"]},"ContactResponse":{"type":"object","properties":{"success":{"type":"boolean","const":true},"message":{"type":"string","description":"Delivery status confirmation."},"demoMode":{"type":"boolean","description":"True when running in demo/placeholder mode."}},"required":["success","message"]},"GithubStatsResponse":{"type":"object","properties":{"totalContributions":{"type":"integer","description":"Total public GitHub contributions."},"totalRepositories":{"type":"integer","description":"Public repositories count."},"totalStars":{"type":"integer","description":"Total stargazers received across repos."},"totalPullRequests":{"type":"integer","description":"Pull requests opened/merged."},"currentStreak":{"type":"integer","description":"Current consecutive contribution days."},"longestStreak":{"type":"integer","description":"Longest consecutive contribution days."},"followers":{"type":"integer","description":"GitHub followers count."},"following":{"type":"integer","description":"GitHub following count."},"totalForks":{"type":"integer","description":"Total repository forks."},"bio":{"type":"string","nullable":true,"description":"GitHub profile bio."},"location":{"type":"string","nullable":true,"description":"Geographic location."},"company":{"type":"string","nullable":true,"description":"Company affiliation."},"blog":{"type":"string","nullable":true,"description":"Blog or portfolio URL."},"twitter":{"type":"string","nullable":true,"description":"Twitter username."},"hireable":{"type":"boolean","nullable":true,"description":"Hireable status flag."}},"required":["totalRepositories","totalStars","followers"]},"ApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","description":"Agent or developer name."},"email":{"type":"string","format":"email","description":"Optional notification email."},"purpose":{"type":"string","description":"Intended integration or evaluation goal."}}},"ApiKeyResponse":{"type":"object","properties":{"success":{"type":"boolean","const":true},"apiKey":{"type":"string","description":"Live generated developer API key."},"tier":{"type":"string","description":"Assigned API access tier."},"rateLimit":{"type":"string","description":"Daily quota and rate limit policy."},"name":{"type":"string","description":"Registered developer name."},"endpoints":{"type":"object","properties":{"rest":{"type":"string"},"mcp":{"type":"string"},"a2a":{"type":"string"},"sandbox":{"type":"string"},"openapi":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"]}},"required":["success","apiKey","tier","rateLimit"]},"JsonRpcRequest":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer","null"]},"method":{"type":"string","description":"Protocol method (e.g. initialize, tools/list, tools/call)."},"params":{"type":"object","description":"Method parameters payload."}},"required":["jsonrpc","method"]},"JsonRpcResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer","null"]},"result":{"type":"object","description":"Method result payload."},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}},"required":["code","message"]}},"required":["jsonrpc"]},"JsonRpcError":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer","null"]},"error":{"type":"object","properties":{"code":{"type":"integer","description":"JSON-RPC error code."},"message":{"type":"string"},"data":{}},"required":["code","message"]}},"required":["jsonrpc","error"]},"McpManifestResponse":{"type":"object","properties":{"$schema":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"protocolVersion":{"type":"string"},"serverInfo":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}},"required":["name","version"]},"capabilities":{"type":"object"},"transport":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string"}},"required":["type","url"]},"endpoints":{"type":"object"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Unique tool name."},"description":{"type":"string","description":"What the tool does and when to call it."},"inputSchema":{"type":"object","description":"JSON schema for tool input arguments."}},"required":["name","description","inputSchema"]},"example":[{"name":"get_profile","description":"Who is Aditya Deokar? Name, role, location, education, contact links, bio and areas of expertise. Use this first when evaluating him for a role.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"search_projects","description":"Search Aditya's production projects. Optionally filter by category (\"ai\", \"frontend\", \"fullstack\") or free-text query. Returns summary cards with tech stacks and outcomes.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"category":{"description":"Category filter","type":"string"},"query":{"description":"Free-text keyword filter","type":"string"}},"additionalProperties":false}},{"name":"get_case_study","description":"Full engineering case study for ONE project by slug (e.g. \"verto-ai\", \"a8n\"). Architecture, features, process timeline, stats. Use after search_projects.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","description":"Project slug from search_projects"}},"required":["slug"],"additionalProperties":false}},{"name":"get_experience","description":"Professional work experience and internship history with impact statements.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"get_blog_posts","description":"Published engineering articles and case studies with tags and reading time.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"request_intro","description":"Contact channels plus a suggested intro message template for reaching out about roles or projects.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}]}},"required":["name","title","version","protocolVersion","tools"]},"McpToolCatalog":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Unique tool name."},"description":{"type":"string","description":"What the tool does and when to call it."},"inputSchema":{"type":"object","description":"JSON schema for tool input arguments."}},"required":["name","description","inputSchema"]},"example":[{"name":"get_profile","description":"Who is Aditya Deokar? Name, role, location, education, contact links, bio and areas of expertise. Use this first when evaluating him for a role.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"search_projects","description":"Search Aditya's production projects. Optionally filter by category (\"ai\", \"frontend\", \"fullstack\") or free-text query. Returns summary cards with tech stacks and outcomes.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"category":{"description":"Category filter","type":"string"},"query":{"description":"Free-text keyword filter","type":"string"}},"additionalProperties":false}},{"name":"get_case_study","description":"Full engineering case study for ONE project by slug (e.g. \"verto-ai\", \"a8n\"). Architecture, features, process timeline, stats. Use after search_projects.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","description":"Project slug from search_projects"}},"required":["slug"],"additionalProperties":false}},{"name":"get_experience","description":"Professional work experience and internship history with impact statements.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"get_blog_posts","description":"Published engineering articles and case studies with tags and reading time.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"request_intro","description":"Contact channels plus a suggested intro message template for reaching out about roles or projects.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}]},"AgentCardResponse":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"protocolVersion":{"type":"string"},"skills":{"type":"array","items":{"type":"object"}},"endpoints":{"type":"object"}},"required":["name","version","protocolVersion","skills"]},"OpenApiSpec":{"type":"object","properties":{"openapi":{"type":"string","const":"3.1.0"},"info":{"type":"object"},"paths":{"type":"object"},"components":{"type":"object"}},"required":["openapi","info","paths"]}}}}