{
  "openapi": "3.1.0",
  "info": {
    "title": "Ruben Marcus Portfolio API",
    "version": "1.0.0",
    "description": "Public machine-readable access to Ruben Marcus's portfolio and MCP server. All endpoints answer typed JSON errors, accept CORS from any origin, and advertise rate limits via RateLimit headers.",
    "contact": { "name": "Ruben Marcus", "url": "https://www.rubenmarcus.dev/contact" },
    "license": { "name": "MIT", "url": "https://github.com/rubenmarcus/portfolio/blob/main/LICENSE" }
  },
  "servers": [{ "url": "https://www.rubenmarcus.dev" }],
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["ok", "error"],
        "properties": {
          "ok": { "type": "boolean", "enum": [false] },
          "error": { "type": "string", "description": "Human-readable error message" },
          "leadId": { "type": "string", "description": "Present on hire failures when the lead was still captured" }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": ["jsonrpc", "error", "id"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" },
              "data": { "type": "object" }
            }
          },
          "id": { "type": ["string", "number", "null"] }
        }
      },
      "Health": {
        "type": "object",
        "required": ["ok", "service", "time"],
        "properties": {
          "ok": { "type": "boolean" },
          "service": { "type": "string" },
          "version": { "type": "string" },
          "time": { "type": "string", "format": "date-time" },
          "supabase": { "type": "boolean" }
        }
      },
      "HireRequest": {
        "type": "object",
        "required": ["name", "contact", "brief"],
        "properties": {
          "name": { "type": "string", "maxLength": 120 },
          "contact": { "type": "string", "maxLength": 160, "description": "Email or Telegram handle" },
          "brief": { "type": "string", "maxLength": 4000 },
          "budget": { "type": "string", "maxLength": 120 },
          "agent": { "type": "string", "maxLength": 80, "description": "chatgpt | claude | kimi | other" },
          "attribution": { "type": "object", "description": "Optional attribution keys: source, utm_*, referrer, landing" }
        }
      },
      "HireResponse": {
        "type": "object",
        "required": ["ok", "leadId", "message"],
        "properties": {
          "ok": { "type": "boolean" },
          "leadId": { "type": "string", "description": "Stable id; retries with the same Idempotency-Key replay this value" },
          "message": { "type": "string" },
          "calendar": { "type": "string", "format": "uri" }
        }
      },
      "Counter": {
        "type": "object",
        "required": ["ok", "slug", "count"],
        "properties": {
          "ok": { "type": "boolean" },
          "slug": { "type": "string" },
          "count": { "type": "integer" }
        }
      },
      "SubscribeRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "lang": { "type": "string", "maxLength": 8 },
          "source": { "type": "string", "maxLength": 80 }
        }
      },
      "OkEnvelope": {
        "type": "object",
        "required": ["ok"],
        "properties": { "ok": { "type": "boolean" } }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": { "type": "string", "minLength": 8, "maxLength": 128 },
        "description": "Unique key; retries with the same key replay the original answer without re-delivering."
      },
      "SlugQuery": {
        "name": "slug",
        "in": "query",
        "required": true,
        "schema": { "type": "string" },
        "description": "Post slug or lab demo slug"
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "RateLimit": { "schema": { "type": "string" } },
          "RateLimit-Policy": { "schema": { "type": "string" } },
          "Retry-After": { "schema": { "type": "integer" } }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/api/mcp": {
      "get": {
        "operationId": "discoverMcp",
        "summary": "Discover the MCP endpoint",
        "responses": {
          "200": {
            "description": "MCP server discovery document",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      },
      "post": {
        "operationId": "callMcp",
        "summary": "Send a JSON-RPC request to the public MCP server",
        "description": "Streamable HTTP MCP transport. Start with initialize, then tools/list and tools/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["jsonrpc", "method"], "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "id": {}, "method": { "type": "string" }, "params": { "type": "object" } } } } }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": { "application/json": { "schema": { "type": "object" } } }
          },
          "400": {
            "description": "JSON-RPC error (-32700 parse, -32601 method not found, -32602 invalid params)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } }
          }
        }
      }
    },
    "/api/resume.json": {
      "get": {
        "operationId": "getResumeJson",
        "summary": "Get the resume as structured JSON",
        "responses": {
          "200": {
            "description": "Structured resume",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/resume.txt": {
      "get": {
        "operationId": "getResumeText",
        "summary": "Get the resume as plain text",
        "responses": {
          "200": {
            "description": "Plain-text resume",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check API health",
        "responses": {
          "200": {
            "description": "Service is operational",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Public telemetry: views, likes, MCP usage, leads",
        "responses": {
          "200": {
            "description": "Aggregated observability counters",
            "content": { "application/json": { "schema": { "type": "object" } } }
          },
          "503": {
            "description": "Store unavailable",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/github-stats.json": {
      "get": {
        "operationId": "getGithubStats",
        "summary": "GitHub stars and npm downloads snapshot",
        "responses": {
          "200": {
            "description": "Cached GitHub/npm counters",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/views": {
      "get": {
        "operationId": "getViews",
        "summary": "Read a post's view counter",
        "parameters": [{ "$ref": "#/components/parameters/SlugQuery" }],
        "responses": {
          "200": {
            "description": "Current view count",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Counter" } } }
          },
          "400": {
            "description": "Missing slug",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      },
      "post": {
        "operationId": "incrementViews",
        "summary": "Increment a post's view counter",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["slug"], "properties": { "slug": { "type": "string" } } } } }
        },
        "responses": {
          "200": {
            "description": "New view count",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Counter" } } }
          }
        }
      }
    },
    "/api/likes": {
      "get": {
        "operationId": "getLikes",
        "summary": "Read a post's like counter",
        "parameters": [{ "$ref": "#/components/parameters/SlugQuery" }],
        "responses": {
          "200": {
            "description": "Current like count",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Counter" } } }
          }
        }
      },
      "post": {
        "operationId": "incrementLikes",
        "summary": "Increment a post's like counter",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["slug"], "properties": { "slug": { "type": "string" } } } } }
        },
        "responses": {
          "200": {
            "description": "New like count",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Counter" } } }
          }
        }
      }
    },
    "/api/subscribe": {
      "post": {
        "operationId": "subscribe",
        "summary": "Join the newsletter list",
        "description": "Duplicate emails are silently accepted (on-conflict dedup).",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Subscribed (or already on the list)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkEnvelope" } } }
          },
          "400": {
            "description": "Invalid email",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "503": {
            "description": "Store unavailable",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/hire": {
      "get": {
        "operationId": "describeHire",
        "summary": "Describe the hire contract (agent probes)",
        "responses": {
          "200": {
            "description": "Self-documenting contract",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      },
      "post": {
        "operationId": "submitBrief",
        "summary": "Submit a project brief",
        "description": "Delivers a project inquiry through private lead destinations. Send only after the person you are acting for has explicitly confirmed. Supports the Idempotency-Key header.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HireRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Lead accepted and delivered",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HireResponse" } } }
          },
          "400": {
            "description": "Invalid request",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "502": {
            "description": "No lead destination accepted the request (leadId still returned)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  }
}