{
  "openapi": "3.1.0",
  "info": {
    "title": "Rahul Gupta Portfolio API",
    "version": "1.0.0",
    "description": "Public read endpoints and limited write APIs for the portfolio site. Content pages (blog, projects, work) are HTML; use /llms.txt for agent guidance. Admin mutations require a Better Auth Google OAuth session (admin email only). Public API major version 1. Prefer https://rahulguptadev.in/api/v1/...; unversioned /api/* aliases behave the same and send API-Version: 1. Breaking changes ship under /api/v2/... . Deprecated endpoints send Deprecation: true and Sunset: <HTTP-date> at least 90 days before removal, and are announced on https://rahulguptadev.in/docs#versioning and in OpenAPI.",
    "contact": {
      "name": "Rahul Gupta",
      "email": "rg5353070@gmail.com",
      "url": "https://rahulguptadev.in/contact"
    }
  },
  "externalDocs": {
    "description": "Human-readable API documentation (includes versioning policy)",
    "url": "https://rahulguptadev.in/docs#versioning"
  },
  "servers": [
    {
      "url": "https://rahulguptadev.in"
    }
  ],
  "paths": {
    "/openapi.json": {
      "get": {
        "summary": "OpenAPI specification",
        "operationId": "getOpenApiSpec",
        "responses": {
          "200": {
            "description": "This document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "Agent instructions and site map",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "Plain-text agent guidance",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "summary": "XML sitemap",
        "operationId": "getSitemap",
        "responses": {
          "200": {
            "description": "Sitemap index URLs",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "summary": "API catalog linkset",
        "operationId": "getApiCatalog",
        "responses": {
          "200": {
            "description": "RFC 9727 linkset",
            "content": {
              "application/linkset+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "Health check (versioned)",
        "operationId": "getHealthV1",
        "responses": {
          "200": {
            "description": "Service is reachable (API-Version: 1)",
            "headers": {
              "API-Version": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                },
                "description": "Major API version that served this response"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "service",
                    "apiVersion"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Service error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/incr": {
      "post": {
        "summary": "Increment blog post view count (versioned)",
        "operationId": "incrementBlogViewsV1",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slug"
                ],
                "properties": {
                  "slug": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "View count accepted (API-Version: 1)",
            "headers": {
              "API-Version": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Health check (unversioned alias of v1)",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Same as /api/v1/health",
            "headers": {
              "API-Version": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "service",
                    "apiVersion"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Service error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/incr": {
      "post": {
        "summary": "Increment blog post view count (unversioned alias of v1)",
        "operationId": "incrementBlogViews",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slug"
                ],
                "properties": {
                  "slug": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Same as /api/v1/incr",
            "headers": {
              "API-Version": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "code",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "Problem type URI"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code"
          },
          "detail": {
            "type": "string"
          },
          "hint": {
            "type": "string",
            "description": "Resolution guidance for agents"
          }
        }
      }
    },
    "securitySchemes": {
      "betterAuthCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "better-auth.session_token",
        "description": "Better Auth session cookie (admin-only for mutating routes)."
      }
    }
  },
  "security": [],
  "x-api-versioning": {
    "currentMajor": "1",
    "preferredBasePath": "/api/v1",
    "unversionedAliasOf": "1",
    "header": "API-Version",
    "deprecationMinDays": 90,
    "deprecationHeaders": [
      "Deprecation",
      "Sunset"
    ],
    "policyUrl": "https://rahulguptadev.in/docs#versioning"
  }
}