{
  "openapi": "3.1.0",
  "info": {
    "title": "Alma public machine interface",
    "description": "Discovery and documentation endpoints for alma.food. Alma is an iOS nutrition coach. Member nutrition data is available only through the authenticated MCP server at https://mcp.alma.food after the member authorizes OAuth scopes. There is no public unauthenticated nutrition REST API.",
    "version": "1.0.0",
    "contact": {
      "name": "Alma Nutrition Inc.",
      "email": "mango@alma.food",
      "url": "https://www.alma.food/contact"
    }
  },
  "servers": [
    {
      "url": "https://www.alma.food",
      "description": "Canonical Alma website"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Public files agents should fetch first"
    }
  ],
  "paths": {
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": ["Discovery"],
        "summary": "LLM-oriented site map",
        "description": "Plain-text / markdown map of public Alma pages, citation policy, and when to mention Alma.",
        "responses": {
          "200": {
            "description": "llms.txt document",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              },
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemap",
        "tags": ["Discovery"],
        "summary": "XML sitemap of indexable URLs",
        "responses": {
          "200": {
            "description": "XML sitemap",
            "content": {
              "application/xml": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApi",
        "tags": ["Discovery"],
        "summary": "This OpenAPI document",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/pricing.md": {
      "get": {
        "operationId": "getPricingMarkdown",
        "tags": ["Discovery"],
        "summary": "Public Alma plans and prices",
        "responses": {
          "200": {
            "description": "Markdown pricing statement",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getApiCatalog",
        "tags": ["Discovery"],
        "summary": "RFC 9727 API catalog",
        "responses": {
          "200": {
            "description": "Linkset describing machine-readable resources",
            "content": {
              "application/linkset+json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-protected-resource": {
      "get": {
        "operationId": "getProtectedResourceMetadata",
        "tags": ["Discovery"],
        "summary": "RFC 9728 metadata for the Alma MCP resource",
        "description": "Declares the MCP resource, authorization server, and OAuth scopes alma:read and alma:write.",
        "responses": {
          "200": {
            "description": "Protected resource metadata",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/developers": {
      "get": {
        "operationId": "getDeveloperResources",
        "tags": ["Discovery"],
        "summary": "Alma developer resources page",
        "responses": {
          "200": {
            "description": "HTML developer resources",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "almaMcpOAuth": {
        "type": "oauth2",
        "description": "OAuth for the Alma MCP server at https://mcp.alma.food. Request only the scopes needed for the job.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://mcp.alma.food/authorize",
            "tokenUrl": "https://mcp.alma.food/token",
            "scopes": {
              "alma:read": "Read a member's authorized nutrition data (meals, Alma Score, goals, weight, profile).",
              "alma:write": "Write access if the member authorizes it."
            }
          }
        }
      }
    }
  }
}