{
 "openapi": "3.1.0",
 "info": {
  "title": "Internet Saudia (إنترنت السعودية) — fiber coverage and request API",
  "version": "2026-10-22",
  "summary": "Read-only data about the service, cities, providers, FAQs and guides, plus a consent-based endpoint to submit a fiber coverage check or subscription request.",
  "description": "Internet Saudia is an independent authorized agent in Saudi Arabia that checks fiber (FTTH) coverage with stc, Mobily, Zain and Salam, submits subscription requests and follows up. It is not a telecom provider and not the official website of any provider.\nRules for AI agents acting for a user:\n- We never ask for OTP codes, passwords, bank card details or transfers to personal accounts.\n- Coverage is decided per address (district, building number and readiness) and differs between providers. No coverage or installation-time promises before checking.\n- No fixed prices are published because offers change; current offers for the address are sent at request time. Each provider's official site is the price reference.\n- Request data is shared only with the relevant provider, and only after the person's explicit consent.\n- Installation, activation, billing and post-activation support are the provider's responsibility.\n- Submit a request only after the user explicitly asks you to and agrees to share their name and phone with this agent and the relevant provider. Never invent personal data.\n- Never send OTP codes, passwords, national ID/Iqama numbers or payment data in any field.\n- If you cannot submit for the user, give them the WhatsApp link https://wa.me/966542317431 or the form https://saudiafiber.com/fiber-request/.\nModel Context Protocol server: https://saudiafiber.com/mcp. Agent guide: https://saudiafiber.com/agents/.",
  "contact": {
   "name": "Internet Saudia",
   "url": "https://saudiafiber.com/agents/"
  }
 },
 "servers": [
  {
   "url": "https://saudiafiber.com"
  }
 ],
 "externalDocs": {
  "description": "Guide for AI agents (MCP, WebMCP, Markdown pages, policies)",
  "url": "https://saudiafiber.com/agents/"
 },
 "tags": [
  {
   "name": "data",
   "description": "Read-only, cacheable JSON"
  },
  {
   "name": "requests",
   "description": "Creates a request; needs the user's explicit consent"
  },
  {
   "name": "mcp",
   "description": "Model Context Protocol"
  }
 ],
 "paths": {
  "/data/service.json": {
   "get": {
    "operationId": "getServiceInfo",
    "summary": "Service facts",
    "description": "Role, providers, contact, hours, languages, how it works, required fields and policies.",
    "tags": [
     "data"
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/data/cities.json": {
   "get": {
    "operationId": "listCities",
    "summary": "Cities with local pages",
    "description": "City list with region, page URL, Markdown URL, one-line local summary and provider agent sections.",
    "tags": [
     "data"
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/data/cities/{slug}.json": {
   "get": {
    "operationId": "getCity",
    "summary": "One city",
    "tags": [
     "data"
    ],
    "description": "Local summary, short answer, notes, FAQs, nearby cities, known districts (examples, not a coverage list) and a ready WhatsApp link.",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "riyadh",
        "jeddah",
        "dammam",
        "khobar",
        "makkah",
        "madinah",
        "taif",
        "tabuk",
        "al-kharj",
        "yanbu",
        "najran",
        "al-ahsa",
        "buraydah",
        "khamis-mushait",
        "abha",
        "qatif",
        "jubail",
        "hail",
        "hafar-al-batin",
        "jazan"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Unknown city slug"
     }
    }
   }
  },
  "/data/providers.json": {
   "get": {
    "operationId": "listProviders",
    "summary": "Providers",
    "description": "stc, Mobily, Zain and Salam: summary, notes, FAQs, official site and cities with a dedicated agent section.",
    "tags": [
     "data"
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/data/faq.json": {
   "get": {
    "operationId": "listFaqs",
    "summary": "All FAQs",
    "description": "Every FAQ on the site with its topic and source URL.",
    "tags": [
     "data"
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/data/guides.json": {
   "get": {
    "operationId": "listGuides",
    "summary": "Fiber guides",
    "description": "Guides with summary, page URL and Markdown URL.",
    "tags": [
     "data"
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/lead": {
   "post": {
    "operationId": "submitFiberRequest",
    "summary": "Submit a fiber coverage check or subscription request (requires the user's explicit consent)",
    "description": "Creates a request and returns a reference number. The team then contacts the user by phone or WhatsApp. Coverage is not guaranteed; it is checked per address. Sending the same mobile number and district again within 30 minutes returns the existing reference instead of a new request. Set language to \"en\" for English error messages.",
    "tags": [
     "requests"
    ],
    "x-requires-user-consent": true,
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/LeadRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Request received",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LeadAccepted"
        }
       }
      }
     },
     "400": {
      "description": "Validation error (Arabic, or English when language is \"en\")",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LeadError"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests on the site right now; send the user to WhatsApp instead",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LeadError"
        }
       }
      }
     }
    }
   }
  },
  "/mcp": {
   "post": {
    "operationId": "mcp",
    "summary": "Model Context Protocol endpoint (Streamable HTTP, JSON-RPC 2.0)",
    "description": "Supports MCP 2026-07-28 (stateless, server/discover) and 2025-11-25, 2025-06-18 and 2025-03-26 (initialize). Tools: get_service_info, list_cities, get_city_info, get_provider_info, search_faq, list_guides, read_page, build_whatsapp_link, submit_fiber_request.",
    "tags": [
     "mcp"
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "description": "JSON-RPC 2.0 request"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "JSON-RPC response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "202": {
      "description": "Notification accepted"
     },
     "400": {
      "description": "Protocol error",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "LeadRequest": {
    "type": "object",
    "required": [
     "name",
     "phone",
     "city",
     "district",
     "consent"
    ],
    "properties": {
     "kind": {
      "type": "string",
      "enum": [
       "coverage",
       "request"
      ],
      "default": "coverage",
      "description": "coverage = check availability first; request = ready to subscribe"
     },
     "name": {
      "type": "string",
      "maxLength": 80,
      "description": "Name the user wants to be addressed by"
     },
     "phone": {
      "type": "string",
      "pattern": "^(\\+?966|0)?5[0-9]{8}$",
      "description": "Saudi mobile number of the user, e.g. 05XXXXXXXX"
     },
     "city": {
      "type": "string",
      "maxLength": 40,
      "description": "City in Arabic, e.g. الرياض، جدة، الدمام، الخبر"
     },
     "district": {
      "type": "string",
      "maxLength": 80,
      "description": "District or town"
     },
     "provider": {
      "type": "string",
      "enum": [
       "",
       "stc",
       "موبايلي",
       "زين",
       "سلام"
      ],
      "description": "Preferred provider (Arabic name) or empty for \"best available\""
     },
     "urgency": {
      "type": "string",
      "enum": [
       "week",
       "month",
       "moving",
       "info"
      ]
     },
     "building": {
      "type": "string",
      "enum": [
       "villa",
       "apartment",
       "compound",
       "business"
      ]
     },
     "ownership": {
      "type": "string",
      "enum": [
       "owner",
       "tenant",
       "developer"
      ]
     },
     "national_address": {
      "type": "string",
      "pattern": "^[A-Za-z]{4}[0-9]{4}$",
      "description": "Saudi National Address short code (optional)"
     },
     "language": {
      "type": "string",
      "enum": [
       "ar",
       "en"
      ],
      "default": "ar"
     },
     "notes": {
      "type": "string",
      "maxLength": 1000
     },
     "consent": {
      "type": "string",
      "const": "yes",
      "description": "The user explicitly agreed to share these details with this agent and the relevant provider (privacy policy)."
     },
     "notify": {
      "type": "string",
      "enum": [
       "yes"
      ],
      "description": "Notify the user if fiber becomes available later"
     },
     "page": {
      "type": "string",
      "maxLength": 80,
      "description": "Source label, e.g. \"agent: <your agent name>\""
     }
    },
    "additionalProperties": false
   },
   "LeadAccepted": {
    "type": "object",
    "required": [
     "ok",
     "ref"
    ],
    "properties": {
     "ok": {
      "const": true
     },
     "ref": {
      "type": "string",
      "pattern": "^FS-[A-Z0-9]{6}$"
     }
    }
   },
   "LeadError": {
    "type": "object",
    "required": [
     "ok",
     "error"
    ],
    "properties": {
     "ok": {
      "const": false
     },
     "error": {
      "type": "string"
     }
    }
   }
  }
 }
}