{
  "openapi": "3.1.0",
  "info": {
    "title": "John Operio Recruiter Assistant API",
    "version": "2.0.0",
    "description": "Recruiter-safe, citation-backed questions about John Operio using approved resume sources only. Conversation traces are recorded with secrets and personal data masked."
  },
  "servers": [{ "url": "https://jjodesignhub.com" }],
  "paths": {
    "/api/chat": {
      "get": {
        "operationId": "describeJohnAssistant",
        "summary": "Describe the assistant and its scope",
        "responses": { "200": { "description": "Assistant description" } }
      },
      "post": {
        "operationId": "askAboutJohnOperio",
        "summary": "Ask a recruiter-safe question about John Operio",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["messages"],
                "properties": {
                  "messages": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 12,
                    "items": {
                      "type": "object",
                      "required": ["role", "content"],
                      "properties": {
                        "role": { "type": "string", "enum": ["user", "assistant"] },
                        "content": { "type": "string", "maxLength": 2000 }
                      }
                    }
                  },
                  "threadId": { "type": "string", "maxLength": 64 },
                  "page": { "type": "string", "maxLength": 120 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Grounded answer, validated source citations, and public contact details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["answer", "contact", "sourcePolicy", "remainingQuestions"],
                  "properties": {
                    "answer": { "type": "string" },
                    "citations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["source", "sourceId"],
                        "properties": {
                          "source": { "type": "string" },
                          "sourceId": { "type": "string" }
                        }
                      }
                    },
                    "contact": {
                      "type": "object",
                      "properties": {
                        "email": { "type": "string", "format": "email" },
                        "phone": { "type": "string" }
                      }
                    },
                    "sourcePolicy": { "type": "string" },
                    "remainingQuestions": { "type": "integer", "minimum": 0, "maximum": 20 }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request" },
          "429": { "description": "Session question limit or per-IP request limit reached" },
          "503": { "description": "Assistant is not configured" }
        }
      }
    }
  }
}