{
  "openapi": "3.1.0",
  "info": {
    "title": "How Good It Can Getâ„¢ Clarity OS",
    "version": "1.0.0",
    "description": "Public interface for How Good It Can Getâ„¢ Clarity OSâ„¢, a governed, provider-independent, nonclinical clarity system. Ordinary Clarity OS execution is available without payment. Protected resources, premium archives, licensed assets, and bulk knowledge products remain separately entitlement- or payment-governed.",
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://ai.howgooditcanget.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402Payment": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment"
      }
    }
  },
  "paths": {
    "/clarity": {
      "post": {
        "operationId": "executeClarityOS",
        "summary": "Execute Clarity OS",
        "description": "Processes the supplied input through the governed Clarity OS runtime. The Clarity Protocolâ„¢ may inform the result but is not the runtime itself. Ordinary execution does not require x402 payment.",
        "security": [],
        "tags": [
          "Clarity OS"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "message"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "The user's anxious, looping, reactive, or decision-friction text input.",
                    "minLength": 1
                  }
                }
              },
              "examples": {
                "example": {
                  "summary": "Clarity OS request",
                  "value": {
                    "message": "I keep replaying a conversation and cannot tell whether I am solving anything or just looping."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful governed Clarity OS response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "paid": {
                      "type": "boolean"
                    },
                    "provider": {
                      "type": "string"
                    },
                    "output": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid message."
          },
          "500": {
            "description": "Internal server error."
          }
        },
        "x-safety": {
          "classification": "non-clinical educational clarity framework",
          "not_for": [
            "therapy",
            "medical diagnosis",
            "medical treatment",
            "crisis intervention",
            "emergency support"
          ],
          "crisis_guidance": "If a user appears to be in immediate danger, expresses intent to self-harm, or discloses a crisis or emergency, do not use this endpoint as the primary response. Direct the user to local emergency, crisis, or professional support."
        }
      }
    },
    "/mcp": {
      "get": {
        "operationId": "getMcpManifest",
        "summary": "Get MCP endpoint information",
        "description": "Returns public discovery information for the How Good It Can Getâ„¢ Clarity OS MCP interface.",
        "security": [],
        "responses": {
          "200": {
            "description": "MCP endpoint information returned."
          },
          "400": {
            "description": "Invalid request."
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns basic service health information.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is reachable."
          },
          "400": {
            "description": "Invalid request."
          }
        }
      }
    },
    "/knowledge/item/{knowledge_id}": {
      "get": {
        "operationId": "getIndividualHGICGKnowledge",
        "summary": "Retrieve one governed HGICG knowledge item for free",
        "parameters": [
          {
            "name": "knowledge_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Governed HGICG knowledge item"
          },
          "404": {
            "description": "Knowledge item not found"
          }
        }
      }
    },
    "/knowledge/bulk-snapshot": {
      "get": {
        "operationId": "getBulkHGICGKnowledgeSnapshot",
        "summary": "Retrieve the current eligible HGICG governed knowledge corpus",
        "description": "Paid by the requesting agent or system; human end users are not charged.",
        "responses": {
          "200": {
            "description": "Authorized bulk knowledge snapshot"
          },
          "402": {
            "description": "Agent/system payment required"
          }
        }
      }
    }
  }
}