{
  "openapi": "3.1.0",
  "info": {
    "title": "StarInterview Agent API",
    "version": "1.0.0",
    "description": "Read-only public data API for StarInterview, a free STAR-method interview practice tool. Exposes the same question library that powers the site's interview-question pages. No authentication required.",
    "contact": { "email": "support@starinterview.org" }
  },
  "servers": [{ "url": "https://starinterview.org", "description": "Production" }],
  "paths": {
    "/api/agent/questions": {
      "get": {
        "summary": "Search the public STAR interview question library",
        "description": "Returns interview-question pages (role/company/competency/scenario types). Omit all params to list pages. Pass q= to search titles/questions/FAQs, type= to filter, slug= to fetch one page's full content.",
        "parameters": [
          { "name": "q", "in": "query", "description": "Free-text search term, e.g. conflict, leadership, software engineer", "schema": { "type": "string" } },
          { "name": "type", "in": "query", "description": "Page type filter", "schema": { "type": "string", "enum": ["role", "company", "competency", "scenario"] } },
          { "name": "slug", "in": "query", "description": "Fetch one page by id; returns full content including STAR examples, tips and FAQs", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "description": "Max results 1-50, default 20", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Search results or a single page record",
            "content": { "application/json": { "schema": { "type": "object" } } }
          },
          "404": {
            "description": "Unknown slug — body contains error=not_found and a hint to use q= search",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP server endpoint (JSON-RPC 2.0)",
        "description": "Model Context Protocol server exposing tools search_questions and get_question_page over the same data. Supports initialize, tools/list, tools/call. Server card: /.well-known/mcp/server-card.json",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["jsonrpc", "method"] } } }
        },
        "responses": {
          "200": { "description": "JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PageSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Stable page slug" },
          "title": { "type": "string" },
          "type": { "type": "string", "enum": ["role", "company", "competency", "scenario"] },
          "questionCount": { "type": "integer" },
          "source_url": { "type": "string", "format": "uri", "description": "Human-readable page on the site" }
        }
      }
    }
  }
}