{
  "openapi": "3.1.0",
  "info": {
    "title": "Shalem API",
    "description": "API for accessing Jewish spiritual reflections and querying the wisdom matching engine.",
    "version": "1.4.0",
    "contact": {
      "name": "Shalem Support",
      "email": "support@shalemapp.com",
      "url": "https://shalemapp.com/developers"
    },
    "license": {
      "name": "Proprietary"
    },
    "termsOfService": "https://shalemapp.com/terms"
  },
  "servers": [
    {
      "url": "https://shalemapp.com",
      "description": "Main Production Server"
    }
  ],
  "paths": {

    "/ask": {
      "post": {
        "operationId": "askWisdom",
        "summary": "Query the Jewish wisdom matching engine",
        "description": "Microsoft NLWeb compatible endpoint. Accepts a natural-language query and returns a Jewish source-text match with reflection and 3-day practice. Supports SSE streaming when client sends `Prefer: streaming` header.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "The emotional state, life event, or spiritual question."
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A relevant spiritual reflection.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_meta": {
                      "type": "object",
                      "properties": {
                        "response_type": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      }
                    },
                    "answer": {
                      "type": "string"
                    },
                    "suggested_queries": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Agent"
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Prefer",
            "schema": {
              "type": "string",
              "enum": [
                "streaming"
              ]
            },
            "required": false,
            "description": "Set to 'streaming' to receive an SSE stream. Otherwise standard JSON response."
          }
        ]
      }
    },
    "/api/agent-view": {
      "get": {
        "tags": [
          "Agent"
        ],
        "operationId": "getAgentView",
        "summary": "Structured agent view",
        "description": "Returns a structured JSON description of Shalem suitable for AI-agent consumption. Equivalent to fetching the homepage with `?mode=agent`. Includes product overview, capabilities, constraints, and links to all relevant well-known files.",
        "responses": {
          "200": {
            "description": "Structured agent view of Shalem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentView"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "Agent"
        ],
        "operationId": "mcpStreamableHttp",
        "summary": "MCP Streamable HTTP transport",
        "description": "Model Context Protocol endpoint over Streamable HTTP transport. See /.well-known/mcp/server-card.json for capabilities. Use a standard MCP client to interact.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MCPRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP JSON-RPC response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MCPResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getLlmsTxt",
        "summary": "Agent-readable summary",
        "description": "Plain-text summary of Shalem for AI agents. Includes product overview, capabilities, constraints, and links.",
        "responses": {
          "200": {
            "description": "Plain-text llms.txt content.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getLlmsFullTxt",
        "summary": "Full agent-readable documentation",
        "description": "Single-document version of the entire Shalem documentation set, suitable for one-shot ingestion by AI agents.",
        "responses": {
          "200": {
            "description": "Plain-text llms-full.txt content.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "tags": [
          "Content"
        ],
        "operationId": "getHomepageMarkdown",
        "summary": "Homepage as markdown",
        "description": "Markdown alternate of the homepage. Also reachable by sending `Accept: text/markdown` to `/`.",
        "responses": {
          "200": {
            "description": "Homepage in markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/pricing.md": {
      "get": {
        "tags": [
          "Content"
        ],
        "operationId": "getPricingMarkdown",
        "summary": "Pricing in markdown",
        "description": "Machine-readable pricing tiers and limits. Used by AI agents for cost comparison.",
        "responses": {
          "200": {
            "description": "Pricing in markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getSitemap",
        "summary": "XML sitemap",
        "responses": {
          "200": {
            "description": "Sitemap of indexable URLs.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Agent",
      "description": "Endpoints designed for AI-agent consumption."
    },
    {
      "name": "Discovery",
      "description": "Metadata and discovery endpoints."
    },
    {
      "name": "Content",
      "description": "Public content (blog, pages) in machine-readable form."
    },
    {
      "name": "Waitlist",
      "description": "Pre-launch waitlist."
    }
  ],
  "components": {
    "schemas": {
      "AgentView": {
        "type": "object",
        "required": [
          "name",
          "description",
          "url",
          "capabilities"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Shalem"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "constraints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "endpoints": {
            "type": "object",
            "properties": {
              "mcp": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "llms_txt": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "AskRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural-language description of the moment, situation, or question.",
            "example": "I'm anxious about a job interview tomorrow."
          },
          "context": {
            "type": "object",
            "description": "Optional context object.",
            "additionalProperties": true
          }
        }
      },
      "AskResponse": {
        "type": "object",
        "required": [
          "_meta",
          "query"
        ],
        "properties": {
          "_meta": {
            "type": "object",
            "required": [
              "response_type",
              "version",
              "request_id",
              "generated_at"
            ],
            "properties": {
              "response_type": {
                "type": "string",
                "enum": [
                  "answer",
                  "tool_call",
                  "no_match"
                ]
              },
              "version": {
                "type": "string",
                "example": "1.0.0"
              },
              "request_id": {
                "type": "string",
                "format": "uuid"
              },
              "generated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "query": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          },
          "citations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string",
                  "example": "Tehillim 23"
                },
                "text": {
                  "type": "string"
                },
                "reference": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "practice": {
            "type": "object",
            "properties": {
              "days": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "day": {
                      "type": "integer"
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "MCPRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "method": {
            "type": "string",
            "example": "tools/list"
          },
          "params": {
            "type": "object"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          }
        }
      },
      "MCPResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "rate_limited",
                "description": "Machine-readable error code."
              },
              "message": {
                "type": "string",
                "example": "Too many requests. Try again in 60 seconds."
              },
              "resolution": {
                "type": "string",
                "description": "Human-readable hint for resolving the error.",
                "example": "Wait for the period indicated in the Retry-After header before retrying."
              },
              "documentation_url": {
                "type": "string",
                "format": "uri",
                "example": "https://shalemapp.com/developers#rate-limits"
              }
            }
          }
        }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded.",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Maximum requests allowed in the current window."
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Requests remaining in the current window."
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            },
            "description": "Unix timestamp when the current window resets."
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait before retrying."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Error": {
        "description": "Error response.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}