{
	"openapi": "3.1.0",
	"info": {
		"title": "sudhanva.me Public API",
		"version": "1.0.0",
		"summary": "Read-only access to Sudhanva Narayana's public profile and writing metadata.",
		"description": "A public, unauthenticated, read-only API for agents, search tools, feed readers, and lightweight integrations. It exposes information already published on sudhanva.me and does not execute workloads or accept private data. The stable API is URL-versioned. Breaking changes use a new major path; any retirement will be announced at least 90 days in advance and signaled with Deprecation and Sunset response headers.",
		"x-api-status": "stable",
		"x-versioning-strategy": "URL major version",
		"x-deprecation-policy": "https://sudhanva.me/developers/versioning/",
		"contact": {
			"name": "Sudhanva Narayana",
			"url": "https://sudhanva.me/contact/",
			"email": "nsudhanva@gmail.com"
		}
	},
	"externalDocs": {
		"description": "Sudhanva API developer documentation",
		"url": "https://sudhanva.me/docs/"
	},
	"servers": [
		{
			"url": "https://sudhanva.me/api/v1",
			"description": "Production API, version 1"
		}
	],
	"tags": [
		{
			"name": "Discovery",
			"description": "Discover the API contract and available resources."
		},
		{
			"name": "Profile",
			"description": "Read Sudhanva Narayana's published professional profile."
		},
		{
			"name": "Posts",
			"description": "Read metadata for published writing."
		}
	],
	"paths": {
		"/": {
			"get": {
				"operationId": "getApiIndex",
				"summary": "Get API discovery information",
				"description": "Returns the API name, version, documentation links, OpenAPI URL, and primary endpoint URLs.",
				"tags": ["Discovery"],
				"parameters": [
					{
						"name": "locale",
						"in": "query",
						"required": false,
						"description": "Response locale. English is the only currently published locale.",
						"schema": { "type": "string", "enum": ["en"], "default": "en" }
					}
				],
				"responses": {
					"200": {
						"description": "API discovery information.",
						"headers": {
							"Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
						},
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ApiIndex"
								}
							}
						}
					},
					"405": {
						"$ref": "#/components/responses/MethodNotAllowed"
					},
					"default": {
						"$ref": "#/components/responses/UnexpectedError"
					},
					"500": {
						"description": "An unexpected server error.",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
							}
						}
					}
				}
			}
		},
		"/profile": {
			"get": {
				"operationId": "getPublicProfile",
				"summary": "Get Sudhanva Narayana's public profile",
				"description": "Returns published professional identity, location, employer, expertise, and canonical public profile links.",
				"tags": ["Profile"],
				"parameters": [
					{
						"name": "locale",
						"in": "query",
						"required": false,
						"description": "Response locale. English is the only currently published locale.",
						"schema": { "type": "string", "enum": ["en"], "default": "en" }
					}
				],
				"responses": {
					"200": {
						"description": "The current published profile.",
						"headers": {
							"Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
						},
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ProfileResponse" }
							}
						}
					},
					"405": {
						"$ref": "#/components/responses/MethodNotAllowed"
					},
					"503": {
						"$ref": "#/components/responses/ServiceUnavailable"
					},
					"default": {
						"$ref": "#/components/responses/UnexpectedError"
					},
					"500": {
						"description": "An unexpected server error.",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
							}
						}
					}
				}
			}
		},
		"/posts": {
			"get": {
				"operationId": "listPublishedPosts",
				"summary": "List published posts",
				"description": "Returns newest-first metadata for published posts, optionally filtered by an exact tag and limited to a requested result count.",
				"tags": ["Posts"],
				"parameters": [
					{
						"name": "limit",
						"in": "query",
						"required": false,
						"description": "Maximum number of posts to return. Defaults to 20.",
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20
						}
					},
					{
						"name": "tag",
						"in": "query",
						"required": false,
						"description": "Exact lowercase post tag to match, such as kubernetes or machine-learning.",
						"schema": {
							"type": "string",
							"minLength": 1,
							"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
						}
					},
					{
						"name": "cursor",
						"in": "query",
						"required": false,
						"description": "Opaque continuation cursor returned as next_cursor by the previous page.",
						"schema": {
							"type": "string",
							"minLength": 1
						}
					}
				],
				"responses": {
					"200": {
						"description": "A filtered page of published post metadata.",
						"headers": {
							"Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
						},
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/PostList"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"405": {
						"$ref": "#/components/responses/MethodNotAllowed"
					},
					"503": {
						"$ref": "#/components/responses/ServiceUnavailable"
					},
					"default": {
						"$ref": "#/components/responses/UnexpectedError"
					},
					"500": {
						"description": "An unexpected server error.",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
							}
						}
					}
				}
			}
		},
		"/posts/{slug}": {
			"get": {
				"operationId": "getPublishedPost",
				"summary": "Get one published post",
				"description": "Returns metadata for the published post identified by its canonical URL slug.",
				"tags": ["Posts"],
				"parameters": [
					{
						"name": "slug",
						"in": "path",
						"required": true,
						"description": "Canonical lowercase, hyphen-separated post slug.",
						"schema": {
							"type": "string",
							"minLength": 1,
							"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Metadata for the requested published post.",
						"headers": {
							"Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
						},
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/PostResponse" }
							}
						}
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"405": {
						"$ref": "#/components/responses/MethodNotAllowed"
					},
					"503": {
						"$ref": "#/components/responses/ServiceUnavailable"
					},
					"default": {
						"$ref": "#/components/responses/UnexpectedError"
					},
					"500": {
						"description": "An unexpected server error.",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"headers": {
			"DeprecationPolicyLink": {
				"description": "RFC 9745 deprecation-policy discovery link. Its presence does not mean this stable API version is deprecated.",
				"schema": { "type": "string" },
				"example": "<https://sudhanva.me/developers/versioning/>; rel=\"deprecation\"; type=\"text/html\""
			}
		},
		"schemas": {
			"ApiIndex": {
				"type": "object",
				"additionalProperties": false,
				"required": [
					"name",
					"version",
					"status",
					"description",
					"documentation_url",
					"openapi_url",
					"versioning_policy_url",
					"mcp_url",
					"cli_url",
					"endpoints"
				],
				"properties": {
					"name": { "type": "string" },
					"version": { "type": "string" },
					"status": { "type": "string", "enum": ["stable"] },
					"description": { "type": "string" },
					"documentation_url": { "type": "string", "format": "uri" },
					"openapi_url": { "type": "string", "format": "uri" },
					"versioning_policy_url": { "type": "string", "format": "uri" },
					"mcp_url": { "type": "string", "format": "uri" },
					"cli_url": { "type": "string", "format": "uri" },
					"endpoints": {
						"type": "object",
						"additionalProperties": false,
						"required": ["profile", "posts"],
						"properties": {
							"profile": { "type": "string", "format": "uri" },
							"posts": { "type": "string", "format": "uri" }
						}
					}
				}
			},
			"Profile": {
				"type": "object",
				"additionalProperties": false,
				"required": [
					"name",
					"jobTitle",
					"specialization",
					"location",
					"url",
					"email",
					"worksFor",
					"knowsAbout",
					"sameAs"
				],
				"properties": {
					"name": { "type": "string" },
					"jobTitle": { "type": "string" },
					"specialization": { "type": "string" },
					"location": { "type": "string" },
					"url": { "type": "string", "format": "uri" },
					"email": { "type": "string", "format": "email" },
					"worksFor": {
						"type": "object",
						"additionalProperties": false,
						"required": ["name", "url"],
						"properties": {
							"name": { "type": "string" },
							"url": { "type": "string", "format": "uri" }
						}
					},
					"knowsAbout": {
						"type": "array",
						"items": { "type": "string" }
					},
					"sameAs": {
						"type": "array",
						"items": { "type": "string", "format": "uri" }
					}
				}
			},
			"ProfileResponse": {
				"type": "object",
				"additionalProperties": false,
				"required": ["profile"],
				"properties": {
					"profile": { "$ref": "#/components/schemas/Profile" }
				}
			},
			"Post": {
				"type": "object",
				"additionalProperties": false,
				"required": [
					"slug",
					"title",
					"description",
					"publishedAt",
					"updatedAt",
					"tags",
					"category",
					"url"
				],
				"properties": {
					"slug": { "type": "string" },
					"title": { "type": "string" },
					"description": { "type": "string" },
					"publishedAt": { "type": "string", "format": "date-time" },
					"updatedAt": { "type": "string", "format": "date-time" },
					"tags": {
						"type": "array",
						"items": { "type": "string" }
					},
					"category": { "type": ["string", "null"] },
					"url": { "type": "string", "format": "uri" }
				}
			},
			"PostResponse": {
				"type": "object",
				"additionalProperties": false,
				"required": ["post"],
				"properties": {
					"post": { "$ref": "#/components/schemas/Post" }
				}
			},
			"PostList": {
				"type": "object",
				"additionalProperties": false,
				"required": ["count", "total", "next_cursor", "posts"],
				"properties": {
					"count": { "type": "integer", "minimum": 0 },
					"total": { "type": "integer", "minimum": 0 },
					"next_cursor": { "type": ["string", "null"] },
					"posts": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/Post" }
					}
				}
			},
			"Error": {
				"type": "object",
				"additionalProperties": false,
				"required": ["code", "message", "hint", "docs_url"],
				"properties": {
					"code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
					"message": { "type": "string" },
					"hint": { "type": "string" },
					"docs_url": { "type": "string", "format": "uri" }
				}
			},
			"ErrorEnvelope": {
				"type": "object",
				"additionalProperties": false,
				"required": ["error"],
				"properties": {
					"error": { "$ref": "#/components/schemas/Error" }
				}
			}
		},
		"responses": {
			"BadRequest": {
				"description": "The request contains an invalid parameter.",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
					}
				}
			},
			"NotFound": {
				"description": "The requested published resource does not exist.",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
					}
				}
			},
			"MethodNotAllowed": {
				"description": "The method is not supported by this read-only API.",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
					}
				}
			},
			"ServiceUnavailable": {
				"description": "The generated public data is temporarily unavailable.",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
					}
				}
			},
			"UnexpectedError": {
				"description": "An unexpected error uses the standard error envelope.",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
					}
				}
			}
		}
	}
}