{
  "openapi": "3.1.0",
  "info": {
    "title": "bharath.sh API",
    "version": "1.0.0",
    "summary": "Newsletter subscription API and agent-readable content surfaces for bharath.sh",
    "description": "Public API for Bharath's personal site. Subscribe or unsubscribe an email address to the 'Thinking Out Loud' newsletter, and fetch machine-readable content: llms.txt site map, per-page markdown via Accept negotiation, and RSS/Atom/JSON feeds.",
    "contact": {
      "name": "Bharath",
      "email": "hi@bharath.sh",
      "url": "https://bharath.sh/contact"
    },
    "license": { "name": "MIT", "url": "https://github.com/bharath31/portfolio" }
  },
  "servers": [{ "url": "https://bharath.sh" }],
  "paths": {
    "/api/subscribe": {
      "post": {
        "operationId": "subscribeToNewsletter",
        "summary": "Subscribe an email to the newsletter",
        "description": "Adds the address to the Resend audience and sends a one-time welcome email. Single opt-in.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmailRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscribed (or already subscribed)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MessageResponse" },
                "examples": {
                  "subscribed": { "value": { "message": "You're subscribed! Check your inbox for a hello." } },
                  "already": { "value": { "message": "You're already subscribed — thank you!" } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadEmail" },
          "500": { "$ref": "#/components/responses/ServerError" }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "curl",
            "source": "curl -X POST https://bharath.sh/api/subscribe -H 'Content-Type: application/json' -d '{\"email\":\"agent@example.com\"}'"
          }
        ]
      }
    },
    "/api/unsubscribe": {
      "post": {
        "operationId": "unsubscribeFromNewsletter",
        "summary": "Unsubscribe an email from the newsletter",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmailRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsubscribed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MessageResponse" },
                "example": { "message": "Successfully unsubscribed" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadEmail" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "Agent site map (llms.txt)",
        "responses": {
          "200": {
            "description": "Markdown site map for AI agents",
            "content": { "text/markdown": {} }
          }
        }
      }
    },
    "/{path}": {
      "get": {
        "operationId": "getPage",
        "summary": "Fetch any page as HTML or markdown",
        "description": "Send Accept: text/markdown to receive the markdown representation (Content-Type: text/markdown). Default browsers receive text/html. Every response carries Vary: Accept, Accept-Encoding. Unknown paths return HTTP 404 whose body is a short markdown site map.",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "examples": { "home": { "value": "" }, "essay": { "value": "writing/mcp" } }
          },
          {
            "name": "Accept",
            "in": "header",
            "schema": { "type": "string" },
            "examples": {
              "html": { "value": "text/html" },
              "markdown": { "value": "text/markdown" }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page in the negotiated representation",
            "content": {
              "text/html": {},
              "text/markdown": {}
            }
          },
          "404": {
            "description": "Not found — markdown body lists where to look next",
            "content": { "text/markdown": {} }
          }
        }
      }
    },
    "/rss.xml": {
      "get": {
        "operationId": "getRssFeed",
        "summary": "RSS 2.0 feed of essays",
        "responses": { "200": { "description": "RSS feed", "content": { "application/rss+xml": {} } } }
      }
    },
    "/atom.xml": {
      "get": {
        "operationId": "getAtomFeed",
        "summary": "Atom feed of essays",
        "responses": { "200": { "description": "Atom feed", "content": { "application/atom+xml": {} } } }
      }
    },
    "/feed.json": {
      "get": {
        "operationId": "getJsonFeed",
        "summary": "JSON Feed 1.1 of essays",
        "responses": { "200": { "description": "JSON Feed", "content": { "application/feed+json": {} } } }
      }
    }
  },
  "components": {
    "schemas": {
      "EmailRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email", "description": "The address to subscribe or unsubscribe." }
        }
      },
      "MessageResponse": {
        "type": "object",
        "properties": { "message": { "type": "string" } }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      }
    },
    "responses": {
      "BadEmail": {
        "description": "Missing or malformed email",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "error": "Valid email is required" }
          }
        }
      },
      "ServerError": {
        "description": "Provider failure — safe to retry",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "error": "Internal server error" }
          }
        }
      }
    }
  }
}