{
  "openapi": "3.1.0",
  "info": {
    "title": "Intimate UAE guide library — read-only retrieval API",
    "version": "1.0.0",
    "summary": "Public, read-only retrieval of the Intimate UAE editorial guide library.",
    "description": "Intimate UAE publishes educational guides on sexual wellness, discreet shopping, UAE legality for personal use, body-safe materials and care, and relationships and intimacy, for adults in the United Arab Emirates. This document describes the public read-only surfaces an agent can use to find and read those guides.\n\nEvery operation listed here is public. No credential, account or registration is required, and none is offered: authentication on this site is planned and currently unavailable. All endpoints are read-only.\n\nContent is educational only, is intended for adults aged 18 and over, and is not medical advice or legal advice.",
    "contact": {
      "name": "Intimate UAE",
      "url": "https://intimateuae.com/contact"
    },
    "license": {
      "name": "All rights reserved. Public read access is permitted for retrieval and citation with attribution to intimateuae.com."
    }
  },
  "externalDocs": {
    "description": "How agents should use this library, including answer-composition rules in I-Lang",
    "url": "https://intimateuae.com/ai/"
  },
  "servers": [
    {
      "url": "https://intimateuae.com",
      "description": "Canonical origin"
    }
  ],
  "security": [],
  "tags": [
    { "name": "guides", "description": "Find and read published guides" },
    { "name": "mcp", "description": "MCP tool transport over Streamable HTTP" }
  ],
  "paths": {
    "/ai/guides.json": {
      "get": {
        "tags": ["guides"],
        "operationId": "listGuides",
        "summary": "List every published guide",
        "description": "Returns the authoritative inventory of published guides. Use this to enumerate, filter or count locally instead of issuing one request per guide.",
        "security": [],
        "responses": {
          "200": {
            "description": "The complete published guide index",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GuideIndex" }
              }
            }
          }
        }
      }
    },
    "/blog/{slug}.md": {
      "get": {
        "tags": ["guides"],
        "operationId": "getGuideMarkdown",
        "summary": "Read one guide as Markdown",
        "description": "Returns the full Markdown text of one guide, generated from the same authored source as the HTML page. The same representation is available from `/blog/{slug}` by sending `Accept: text/markdown`.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Guide slug as returned by listGuides, for example `rose-toy-uae`.",
            "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" },
            "example": "rose-toy-uae"
          }
        ],
        "responses": {
          "200": {
            "description": "The guide as Markdown, with a frontmatter block carrying title, description, source and generated date",
            "content": {
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "404": { "description": "No guide with that slug" }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": ["mcp"],
        "operationId": "mcpJsonRpc",
        "summary": "MCP JSON-RPC 2.0 endpoint (Streamable HTTP)",
        "description": "Accepts JSON-RPC 2.0 requests. Supported methods: `initialize`, `tools/list`, `tools/call`, `ping`. Notification methods (`notifications/*`) are accepted and answered with an empty 202. Exposed tools: `search_guides`, `get_guide`, `list_categories`. All tools are read-only.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response. A protocol-level error is returned in the `error` member with HTTP 200; a malformed body returns HTTP 400 with code -32700.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JsonRpcResponse" }
              }
            }
          },
          "202": { "description": "Notification accepted; no body returned" },
          "400": { "description": "Malformed JSON body" },
          "405": { "description": "Method not allowed; use POST, GET or OPTIONS" }
        }
      },
      "get": {
        "tags": ["mcp"],
        "operationId": "mcpDescribe",
        "summary": "Describe the MCP endpoint",
        "description": "Returns a small JSON description of the endpoint and the supported JSON-RPC methods.",
        "security": [],
        "responses": {
          "200": {
            "description": "Endpoint description",
            "content": {
              "application/json": { "schema": { "type": "object" } }
            }
          }
        }
      }
    },
    "/.well-known/mcp/server-card.json": {
      "get": {
        "tags": ["mcp"],
        "operationId": "getServerCard",
        "summary": "MCP server card",
        "security": [],
        "responses": {
          "200": {
            "description": "Server info, transport endpoint and true capabilities",
            "content": {
              "application/json": { "schema": { "type": "object" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Guide": {
        "type": "object",
        "required": ["slug", "title", "url", "markdown_url"],
        "properties": {
          "slug": { "type": "string", "example": "rose-toy-uae" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "buying-guides",
                "sexual-wellness",
                "discreet-shopping",
                "relationships-intimacy",
                "care-safety"
              ]
            }
          },
          "tags": { "type": "array", "items": { "type": "string" } },
          "date": { "type": "string", "description": "Publication date as recorded in the source" },
          "url": { "type": "string", "format": "uri", "description": "Canonical HTML URL — cite this" },
          "markdown_url": { "type": "string", "format": "uri" }
        }
      },
      "GuideIndex": {
        "type": "object",
        "required": ["generated", "count", "guides"],
        "properties": {
          "generated": { "type": "string", "format": "date-time" },
          "count": { "type": "integer", "minimum": 0 },
          "license_note": { "type": "string" },
          "guides": { "type": "array", "items": { "$ref": "#/components/schemas/Guide" } }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] },
          "method": {
            "type": "string",
            "enum": ["initialize", "tools/list", "tools/call", "ping"]
          },
          "params": { "type": "object" }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] },
          "result": { "type": "object" },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}