{
  "openapi": "3.0.3",
  "info": {
    "title": "Maslow public API",
    "version": "1.0.0",
    "description": "The unauthenticated public surface of maslow.tech, plus the MCP endpoint agents connect to. The full product surface (memory objects, search, files, the per-member Computer) is exposed as MCP tools over /mcp rather than REST — connect an MCP client to discover them; this spec documents what is reachable over plain HTTP.",
    "contact": {
      "name": "Maslow",
      "url": "https://maslow.tech/contact",
      "email": "hello@maslow.tech"
    },
    "license": { "name": "AGPL-3.0", "url": "https://www.gnu.org/licenses/agpl-3.0.html" }
  },
  "servers": [{ "url": "https://maslow.tech" }],
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "description": "Reports whether the service is ready to take traffic. Used by load balancers and uptime monitors; safe to poll. No authentication.",
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Health" } }
            }
          },
          "503": {
            "description": "Service is not ready (draining or degraded).",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Health" } }
            }
          }
        }
      }
    },
    "/api/ping": {
      "get": {
        "operationId": "getPing",
        "summary": "Liveness ping",
        "description": "Zero-dependency liveness probe. Returns the literal text `pong` followed by a server timestamp in milliseconds. No authentication.",
        "responses": {
          "200": {
            "description": "The service is alive.",
            "content": {
              "text/plain": { "schema": { "type": "string", "example": "pong 1755800000000" } }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "postMcp",
        "summary": "MCP endpoint (Streamable HTTP)",
        "description": "The Model Context Protocol endpoint. Connect an MCP client (Claude, or any client speaking MCP Streamable HTTP) to discover and call Maslow's tools: typed memory objects, semantic search, sharing, files, and the per-member Computer. Requires a bearer token issued to your organization — sign in at https://maslow.tech and connect from the dashboard.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON-RPC response (or an SSE stream for long-running calls).",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An agent token for your organization, issued from the Maslow dashboard."
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "description": "Health report.",
        "properties": {
          "ok": { "type": "boolean", "description": "True when ready to serve." },
          "service": { "type": "string", "description": "Always \"box\"." },
          "ready": { "type": "boolean", "description": "Present and false while draining." },
          "reason": { "type": "string", "description": "Why the service is not ready." }
        },
        "required": ["ok", "service"]
      },
      "Error": {
        "type": "object",
        "description": "Structured error envelope returned by API endpoints.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error code, e.g. not_found."
              },
              "message": { "type": "string", "description": "Human-readable explanation." },
              "hint": { "type": "string", "description": "What to try instead." }
            },
            "required": ["code", "message"]
          }
        },
        "required": ["error"]
      },
      "JsonRpcRequest": {
        "type": "object",
        "description": "A JSON-RPC 2.0 request as defined by MCP.",
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": {
            "description": "Request id (string or number).",
            "oneOf": [{ "type": "string" }, { "type": "number" }]
          },
          "method": {
            "type": "string",
            "description": "MCP method, e.g. tools/list or tools/call."
          },
          "params": { "type": "object", "description": "Method parameters." }
        },
        "required": ["jsonrpc", "method"]
      },
      "JsonRpcResponse": {
        "type": "object",
        "description": "A JSON-RPC 2.0 response as defined by MCP.",
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "oneOf": [{ "type": "string" }, { "type": "number" }] },
          "result": { "type": "object" },
          "error": { "type": "object" }
        },
        "required": ["jsonrpc"]
      }
    }
  }
}