{
  "openapi": "3.1.0",
  "info": {
    "title": "Ziv Isaiah - WebMCP & Agentic Experience (AX) API",
    "version": "1.0.0",
    "description": "Deterministic OpenAPI 3.1 and Model Context Protocol (MCP) tool endpoints for autonomous AI agents visiting zivisaiah.com. Enables keyless, rate-limited semantic search across essays, biographical intelligence, and verified contact dispatch.",
    "contact": {
      "name": "Ziv Isaiah",
      "url": "https://www.zivisaiah.com/contact",
      "email": "ziv@zivisaiah.com"
    }
  },
  "servers": [
    {
      "url": "https://www.zivisaiah.com",
      "description": "Production Server"
    },
    {
      "url": "https://dev.zivisaiah.com",
      "description": "Development Server (Tailnet-gated)"
    }
  ],
  "paths": {
    "/api/mcp/essays/search": {
      "get": {
        "operationId": "searchEssays",
        "summary": "Search published essays and technical notes",
        "description": "Performs keyword, semantic, and categorical search across all 19 published essays by Ziv Isaiah.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search keyword or phrase (e.g. 'agentic', 'fraud', 'deepfake')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by taxonomy pillar",
            "schema": {
              "type": "string",
              "enum": [
                "Leadership & Culture",
                "Agentic AI & Security",
                "Deepfake Defense",
                "Product & Engineering Strategy",
                "Frontier AI"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of essays to return (default 10, max 50)",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching essays with metadata, excerpts, and URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": { "type": "string" },
                          "slug": { "type": "string" },
                          "url": { "type": "string" },
                          "date": { "type": "string" },
                          "category": { "type": "string" },
                          "excerpt": { "type": "string" },
                          "readingTime": { "type": "string" }
                        }
                      }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/articles": {
      "get": {
        "operationId": "listAllArticles",
        "summary": "List all published articles and metadata",
        "description": "Returns the complete archive index of published essays and articles.",
        "responses": {
          "200": {
            "description": "Full array of essays.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "articles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": { "type": "string" },
                          "slug": { "type": "string" },
                          "date": { "type": "string" },
                          "category": { "type": "string" },
                          "description": { "type": "string" }
                        }
                      }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/bio": {
      "get": {
        "operationId": "getBiographicalIntelligence",
        "summary": "Retrieve biographical and venture background",
        "description": "Returns verified career timeline, venture history (Clarity, nSure.ai, Zeek), speaking topics, and executive background for Ziv Isaiah.",
        "responses": {
          "200": {
            "description": "Biographical profile data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "role": { "type": "string" },
                    "ventures": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "company": { "type": "string" },
                          "role": { "type": "string" },
                          "period": { "type": "string" },
                          "description": { "type": "string" }
                        }
                      }
                    },
                    "focusAreas": {
                      "type": "array",
                      "items": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/contact": {
      "post": {
        "operationId": "submitAgentContact",
        "summary": "Submit a business inquiry from an autonomous agent",
        "description": "Enables an autonomous AI delegate to deliver a structured introduction, meeting request, or collaboration note to Ziv Isaiah.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "message"],
                "properties": {
                  "name": { "type": "string", "description": "Sender name or agent principal" },
                  "email": { "type": "string", "format": "email", "description": "Verified contact email" },
                  "message": { "type": "string", "description": "Structured message content" },
                  "topic": { "type": "string", "description": "Optional topic or engagement area" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message received successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input with RFC 7807 error format and recovery hints."
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitWebContact",
        "summary": "Direct human contact form submission",
        "description": "Web form submission endpoint with CSRF and rate limiting.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "message"],
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "message": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message dispatched successfully."
          }
        }
      }
    }
  }
}