{
  "openapi": "3.1.0",
  "info": {
    "title": "Tecorva Public API",
    "summary": "The publicly callable surface of tecorva.com.",
    "description": "Tecorva is a Riyadh-based software house building custom software, ERP systems and AI solutions for the Saudi market.\n\nThis document describes only the endpoints that are open to the public internet: booking a consultation and checking service health. The rest of /api/ (bookings, users, analytics, HR, finance, media) is internal tooling behind a JWT session and is deliberately not described here - there is no public sign-up and no OAuth authorization server.",
    "version": "1.0.0",
    "contact": {
      "name": "Tecorva",
      "url": "https://tecorva.com",
      "email": "support@tecorva.com"
    },
    "license": { "name": "Proprietary", "identifier": "LicenseRef-Tecorva-Proprietary" }
  },
  "servers": [{ "url": "https://tecorva.com", "description": "Production" }],
  "externalDocs": {
    "description": "Company facts for AI agents (Markdown)",
    "url": "https://tecorva.com/ai-info.md"
  },
  "paths": {
    "/api/status.php": {
      "get": {
        "operationId": "getStatus",
        "summary": "Service health",
        "description": "Liveness probe for the public API. No authentication, no side effects.",
        "security": [],
        "responses": {
          "200": {
            "description": "The API is up.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Status" },
                "example": {
                  "status": "pass",
                  "service": "tecorva-public-api",
                  "version": "1.0.0",
                  "time": "2026-09-13T09:00:00+00:00",
                  "checks": { "booking": "up", "mcp": "up" }
                }
              }
            }
          }
        }
      }
    },
    "/api/email_booking.php": {
      "post": {
        "operationId": "bookMeeting",
        "summary": "Book a consultation meeting",
        "description": "Creates a consultation request and emails the Tecorva sales team. This is the same endpoint the website booking form uses.\n\nRate limited per IP: 1 request per minute and 5 per day. Exceeding either returns 429 - do not retry in a loop.\n\nSubmit real contact details only: a human replies to every booking, usually within one business hour (Sun-Thu, 09:00-18:00 Asia/Riyadh).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BookingRequest" },
              "example": {
                "name": "Sara Al-Otaibi",
                "email": "sara@example.com",
                "phone": "+966500000000",
                "date": "2026-09-20",
                "time": "14:00",
                "topic": "ERP consultation",
                "service": "Custom ERP System",
                "message": "We need ZATCA Phase 2 compliant invoicing for 40 branches.",
                "language": "en",
                "type": "meeting"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking accepted. `success` is true even when `emailed` is false - the booking is persisted either way and the team still sees it.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BookingResponse" },
                "example": { "success": true, "delivered": true, "meetingLink": "https://meet.google.com/xxx-yyyy-zzz" }
              }
            }
          },
          "400": {
            "description": "Invalid email, or a required field (name, date, time) is missing.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Rate limit hit (1/minute or 5/day per IP).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpJsonRpc",
        "summary": "MCP endpoint (JSON-RPC 2.0)",
        "description": "Read-mostly Model Context Protocol endpoint. See /.well-known/mcp/server-card.json for the server card, or call initialize then tools/list.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object" } } }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Status": {
        "type": "object",
        "required": ["status", "service", "time"],
        "properties": {
          "status": { "type": "string", "enum": ["pass", "fail"] },
          "service": { "type": "string" },
          "version": { "type": "string" },
          "time": { "type": "string", "format": "date-time" },
          "checks": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      },
      "BookingRequest": {
        "type": "object",
        "required": ["name", "email", "date", "time"],
        "properties": {
          "name": { "type": "string", "description": "Contact full name.", "maxLength": 120 },
          "email": { "type": "string", "format": "email", "description": "A reachable business email. Validated server-side." },
          "phone": { "type": "string", "description": "Preferred in E.164, e.g. +966500000000. Sales follows up by phone or WhatsApp." },
          "date": { "type": "string", "description": "Requested date, YYYY-MM-DD. Sunday-Thursday are working days in Saudi Arabia.", "examples": ["2026-09-20"] },
          "time": { "type": "string", "description": "Requested 24h local time (Asia/Riyadh), HH:MM, between 09:00 and 18:00.", "examples": ["14:00"] },
          "topic": { "type": "string", "description": "Short subject line for the meeting.", "default": "Consultation" },
          "service": { "type": "string", "description": "Which Tecorva service this is about. Falls back to topic when omitted." },
          "message": { "type": "string", "description": "Free-text brief: scope, budget, timeline. Newlines allowed." },
          "language": { "type": "string", "enum": ["en", "ar"], "default": "en", "description": "Language for the confirmation email." },
          "type": { "type": "string", "enum": ["meeting", "chatbot", "planner"], "default": "meeting", "description": "Lead source. Agents should send meeting." }
        }
      },
      "BookingResponse": {
        "type": "object",
        "required": ["success"],
        "properties": {
          "success": { "type": "boolean" },
          "delivered": { "type": "boolean", "description": "True when the notification email was accepted by the mail server." },
          "emailed": { "type": "boolean", "description": "Present and false when the booking was saved but the email failed." },
          "mailError": { "type": "string" },
          "meetingLink": { "type": "string", "description": "Google Meet link for the requested slot, when one could be generated." }
        }
      },
      "Error": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string" }
        }
      }
    }
  }
}