{
  "openapi": "3.1.0",
  "info": {
    "title": "Lar dos Velhos Lili Ribeiro - Developer & AI Agent API",
    "description": "Public REST API (v1), Model Context Protocol (MCP) endpoints, machine-readable datasets, and content negotiation for Lar dos Velhos Lili Ribeiro (ILPI in Ribeirão Preto - SP, Brazil, CNPJ 56.015.506/0001-29).\n\n### API Versioning & Deprecation Policy\n- Current API version: `/api/v1/`\n- Deprecation announcements precede endpoint retirement by at least 6 months.\n- Deprecated endpoints include standard `Deprecation` and `Sunset` HTTP headers (RFC 8594).\n- Breaking changes will only be introduced under a new major version prefix (`/v2/`).",
    "version": "1.0.0",
    "contact": {
      "name": "Lar dos Velhos Lili Ribeiro",
      "url": "https://lar-lili-ribeiro.vercel.app/developer/index.html",
      "email": "contato@lardosvelhos.com.br"
    },
    "license": {
      "name": "Open Access / Non-Profit Public Data",
      "url": "https://lar-lili-ribeiro.vercel.app/privacidade.html"
    }
  },
  "x-api-versioning-policy": {
    "version": "1.0.0",
    "strategy": "URI Path Versioning (/api/v1/)",
    "currentVersion": "v1",
    "supportedVersions": ["v1"],
    "sunsetPolicyDays": 180,
    "deprecationHeaders": ["Deprecation", "Sunset", "Link"]
  },
  "servers": [
    {
      "url": "https://lar-lili-ribeiro.vercel.app",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/v1/institution": {
      "get": {
        "operationId": "getInstitutionProfile",
        "summary": "Obter perfil institucional e dados cadastrais",
        "description": "Retorna os dados cadastrais oficiais, CNPJ 56.015.506/0001-29, endereço oficial, contatos e serviços de assistência geriátrica prestados pelo Lar dos Velhos Lili Ribeiro.",
        "responses": {
          "200": {
            "description": "Perfil institucional detalhado",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "Api-Version": { "$ref": "#/components/headers/Api-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstitutionProfile"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails400" },
          "404": { "$ref": "#/components/responses/ProblemDetails404" },
          "429": { "$ref": "#/components/responses/ProblemDetails429" },
          "500": { "$ref": "#/components/responses/ProblemDetails500" }
        }
      }
    },
    "/api/v1/donations": {
      "get": {
        "operationId": "getDonationCoordinates",
        "summary": "Obter coordenadas bancárias e chave PIX para doação",
        "description": "Retorna dados bancários verificados da Caixa Econômica Federal, chave PIX (CNPJ 56.015.506/0001-29) e orientações de dedução no Imposto de Renda (Fundo Municipal do Idoso).",
        "responses": {
          "200": {
            "description": "Coordenadas bancárias e fiscais para doação",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "Api-Version": { "$ref": "#/components/headers/Api-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DonationCoordinates"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails400" },
          "404": { "$ref": "#/components/responses/ProblemDetails404" },
          "429": { "$ref": "#/components/responses/ProblemDetails429" },
          "500": { "$ref": "#/components/responses/ProblemDetails500" }
        }
      }
    },
    "/api/v1/transparency": {
      "get": {
        "operationId": "getTransparencyOverview",
        "summary": "Obter relatórios de governança e prestação de contas",
        "description": "Retorna conformidade com a Lei Federal nº 13.019/2014 (MROSC), links de balanços patrimoniais, DREs e parcerias públicas.",
        "responses": {
          "200": {
            "description": "Indicadores de transparência e governança",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "Api-Version": { "$ref": "#/components/headers/Api-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransparencyOverview"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails400" },
          "404": { "$ref": "#/components/responses/ProblemDetails404" },
          "429": { "$ref": "#/components/responses/ProblemDetails429" },
          "500": { "$ref": "#/components/responses/ProblemDetails500" }
        }
      }
    },
    "/api/v1/projects": {
      "get": {
        "operationId": "getInstitutionalProjects",
        "summary": "Listar projetos sociais e de assistência geriátrica",
        "description": "Retorna projetos ativos voltados ao bem-estar, assistência geriátrica e estimulação física e cognitiva das idosas acolhidas.",
        "responses": {
          "200": {
            "description": "Lista de projetos institucionais ativos",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" },
              "Api-Version": { "$ref": "#/components/headers/Api-Version" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectsList"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails400" },
          "404": { "$ref": "#/components/responses/ProblemDetails404" },
          "429": { "$ref": "#/components/responses/ProblemDetails429" },
          "500": { "$ref": "#/components/responses/ProblemDetails500" }
        }
      }
    },
    "/.well-known/mcp": {
      "get": {
        "operationId": "getMcpServerManifest",
        "summary": "MCP Server Card & Capabilities",
        "description": "Returns Model Context Protocol (MCP) server metadata, protocol version, and streamable HTTP endpoints.",
        "responses": {
          "200": {
            "description": "MCP Server Card manifest",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpServerCard"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails400" },
          "404": { "$ref": "#/components/responses/ProblemDetails404" },
          "429": { "$ref": "#/components/responses/ProblemDetails429" },
          "500": { "$ref": "#/components/responses/ProblemDetails500" }
        }
      },
      "post": {
        "operationId": "handleMcpJsonRpcRequest",
        "summary": "MCP Protocol Handshake & Tool Invocation",
        "description": "Handles live JSON-RPC 2.0 requests for Model Context Protocol (MCP) Streamable HTTP transport including initialize, tools/list, tools/call, resources/list, and resources/read.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpJsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP JSON-RPC response",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails400" },
          "429": { "$ref": "#/components/responses/ProblemDetails429" },
          "500": { "$ref": "#/components/responses/ProblemDetails500" }
        }
      }
    },
    "/api/markdown": {
      "get": {
        "operationId": "getMarkdownNegotiatedPage",
        "summary": "Markdown Content Negotiation Endpoint",
        "description": "Returns a clean, token-efficient Markdown representation of the requested portal path according to acceptmarkdown.com standard.",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "The path to retrieve in markdown format (e.g. index.html, sobre.html)"
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "schema": { "type": "string", "example": "text/markdown" },
            "description": "Set to text/markdown for content negotiation"
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown representation of page",
            "headers": {
              "Content-Type": { "schema": { "type": "string", "example": "text/markdown; charset=utf-8" } },
              "Vary": { "schema": { "type": "string", "example": "Accept, Accept-Encoding" } },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": {
            "description": "Not Found with Markdown recovery instructions",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/ProblemDetails429" }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTextFile",
        "summary": "LLMs Directory & Guidance",
        "description": "Plain-text markdown guide for LLMs and AI agents adhering to llmstxt.org specification.",
        "responses": {
          "200": {
            "description": "llms.txt content",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemapXmlFile",
        "summary": "XML Sitemap",
        "description": "Standard sitemap of all indexable pages for search crawlers and AI indexers.",
        "responses": {
          "200": {
            "description": "XML sitemap content",
            "content": {
              "application/xml": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit-Limit": {
        "description": "The maximum request quota allocated in the current window",
        "schema": { "type": "integer", "example": 100 }
      },
      "RateLimit-Remaining": {
        "description": "The number of remaining requests in the current window",
        "schema": { "type": "integer", "example": 99 }
      },
      "RateLimit-Reset": {
        "description": "The number of seconds remaining until quota resets",
        "schema": { "type": "integer", "example": 60 }
      },
      "RateLimit-Policy": {
        "description": "Quota policy parameters",
        "schema": { "type": "string", "example": "100;w=60" }
      },
      "Api-Version": {
        "description": "Version of the executing API handler",
        "schema": { "type": "string", "example": "1.0.0" }
      }
    },
    "responses": {
      "ProblemDetails400": {
        "description": "Bad Request - RFC 9457 Problem Details",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "ProblemDetails404": {
        "description": "Resource Not Found - RFC 9457 Problem Details",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "ProblemDetails429": {
        "description": "Rate Limit Exceeded - RFC 9457 Problem Details",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying",
            "schema": { "type": "integer", "example": 60 }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "ProblemDetails500": {
        "description": "Internal Server Error - RFC 9457 Problem Details",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 Problem Details for HTTP APIs",
        "required": ["type", "title", "status", "code", "detail"],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "URI identifying the problem type",
            "example": "https://lar-lili-ribeiro.vercel.app/developer/errors#not-found"
          },
          "title": {
            "type": "string",
            "description": "Short human-readable summary of problem",
            "example": "Resource Not Found"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 404
          },
          "code": {
            "type": "string",
            "description": "Application-specific machine-readable error code",
            "example": "RESOURCE_NOT_FOUND"
          },
          "detail": {
            "type": "string",
            "description": "Specific explanation of this occurrence",
            "example": "The requested API endpoint '/api/v1/unknown' does not exist."
          },
          "instance": {
            "type": "string",
            "description": "URI identifying the occurrence of problem",
            "example": "/api/v1/unknown"
          },
          "hint": {
            "type": "string",
            "description": "Resolution suggestion or recovery instruction for AI agents",
            "example": "Check available endpoints at /developer/openapi.json."
          }
        }
      },
      "InstitutionProfile": {
        "type": "object",
        "required": ["entity", "contact", "careServices"],
        "properties": {
          "entity": {
            "type": "object",
            "required": ["name", "legalName", "taxID", "foundingYear", "type", "description"],
            "properties": {
              "name": { "type": "string", "example": "Lar dos Velhos Lili Ribeiro" },
              "legalName": { "type": "string", "example": "Lar dos Velhos da Igreja Presbiteriana" },
              "alternateNames": { "type": "array", "items": { "type": "string" } },
              "taxID": { "type": "string", "example": "56.015.506/0001-29" },
              "foundingYear": { "type": "integer", "example": 1960 },
              "type": { "type": "string", "example": "Instituição de Longa Permanência para Idosas (ILPI)" },
              "description": { "type": "string" }
            }
          },
          "contact": {
            "type": "object",
            "required": ["address", "telephone", "whatsapp", "email", "website"],
            "properties": {
              "address": {
                "type": "object",
                "required": ["street", "neighborhood", "city", "state", "postalCode", "country"],
                "properties": {
                  "street": { "type": "string", "example": "Travessa Pura Pantozzi, 110" },
                  "neighborhood": { "type": "string", "example": "Ipiranga" },
                  "city": { "type": "string", "example": "Ribeirão Preto" },
                  "state": { "type": "string", "example": "SP" },
                  "postalCode": { "type": "string", "example": "14055-609" },
                  "country": { "type": "string", "example": "Brasil" }
                }
              },
              "telephone": { "type": "string", "example": "+55-16-3630-3235" },
              "whatsapp": { "type": "string", "example": "+55-16-3630-3235" },
              "email": { "type": "string", "format": "email", "example": "contato@lardosvelhos.com.br" },
              "website": { "type": "string", "format": "uri", "example": "https://lar-lili-ribeiro.vercel.app/" }
            }
          },
          "careServices": {
            "type": "array",
            "items": { "type": "string" },
            "example": [
              "Enfermagem geriátrica 24 horas",
              "Acompanhamento médico geriatra regular",
              "Fisioterapia motora e preventiva",
              "Nutrição clínica balanceada"
            ]
          }
        }
      },
      "DonationCoordinates": {
        "type": "object",
        "required": ["pix", "bankTransfer", "incomeTaxDeduction"],
        "properties": {
          "pix": {
            "type": "object",
            "required": ["keyType", "key", "beneficiary", "bank", "instructions"],
            "properties": {
              "keyType": { "type": "string", "example": "CNPJ" },
              "key": { "type": "string", "example": "56.015.506/0001-29" },
              "beneficiary": { "type": "string", "example": "Lar dos Velhos da Igreja Presbiteriana" },
              "bank": { "type": "string", "example": "Caixa Econômica Federal (104)" },
              "instructions": { "type": "string" }
            }
          },
          "bankTransfer": {
            "type": "object",
            "required": ["bankName", "bankCode", "agency", "accountNumber", "accountType", "accountHolder", "cnpj"],
            "properties": {
              "bankName": { "type": "string", "example": "Caixa Econômica Federal" },
              "bankCode": { "type": "string", "example": "104" },
              "agency": { "type": "string", "example": "0292" },
              "operation": { "type": "string", "example": "003" },
              "accountNumber": { "type": "string", "example": "642-1" },
              "accountType": { "type": "string", "example": "Pessoa Jurídica" },
              "accountHolder": { "type": "string", "example": "Lar dos Velhos da Igreja Presbiteriana" },
              "cnpj": { "type": "string", "example": "56.015.506/0001-29" }
            }
          },
          "incomeTaxDeduction": {
            "type": "object",
            "required": ["eligibility", "fund", "cost", "submissionEmail"],
            "properties": {
              "eligibility": {
                "type": "object",
                "properties": {
                  "individuals": { "type": "string", "example": "Até 6% do IRPF na declaração completa" },
                  "corporations": { "type": "string", "example": "Até 1% do IRPJ no Lucro Real" }
                }
              },
              "fund": { "type": "string", "example": "Fundo Municipal dos Direitos da Pessoa Idosa de Ribeirão Preto (CMI)" },
              "cost": { "type": "string", "example": "R$ 0,00 adicional - dedução do imposto já devido" },
              "submissionEmail": { "type": "string", "example": "contato@lardosvelhos.com.br" }
            }
          }
        }
      },
      "TransparencyOverview": {
        "type": "object",
        "required": ["regulatoryFramework", "governanceStatus", "documentsUrl", "availableDocuments"],
        "properties": {
          "regulatoryFramework": { "type": "string", "example": "Lei Federal nº 13.019/2014 (MROSC)" },
          "governanceStatus": { "type": "string", "example": "Regular / Auditado" },
          "documentsUrl": { "type": "string", "format": "uri" },
          "availableDocuments": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "ProjectsList": {
        "type": "object",
        "required": ["projects"],
        "properties": {
          "projects": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "title", "objective"],
              "properties": {
                "id": { "type": "string", "example": "saude-longevidade" },
                "title": { "type": "string", "example": "Projeto Saúde & Longevidade" },
                "objective": { "type": "string" }
              }
            }
          }
        }
      },
      "McpServerCard": {
        "type": "object",
        "required": ["version", "protocolVersion", "serverInfo", "transport", "capabilities"],
        "properties": {
          "version": { "type": "string", "example": "1.0.0" },
          "protocolVersion": { "type": "string", "example": "2024-11-05" },
          "serverInfo": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "example": "lar-dos-velhos-lili-ribeiro-mcp" },
              "title": { "type": "string" },
              "description": { "type": "string" },
              "version": { "type": "string", "example": "1.0.0" }
            }
          },
          "transport": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "example": "streamable-http" },
              "url": { "type": "string", "format": "uri" }
            }
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "tools": { "type": "object" },
              "resources": { "type": "object" },
              "prompts": { "type": "object" }
            }
          }
        }
      },
      "McpJsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method", "id"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "method": {
            "type": "string",
            "enum": ["initialize", "tools/list", "tools/call", "resources/list", "resources/read", "ping"]
          },
          "params": { "type": "object" },
          "id": { "type": ["string", "integer"], "example": 1 }
        }
      },
      "McpJsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer"], "example": 1 },
          "result": { "type": "object" },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" },
              "data": { "type": "object" }
            }
          }
        }
      }
    }
  }
}