{
  "openapi": "3.1.0",
  "info": {
    "title": "MonitorMojo Public API",
    "version": "1.0.0",
    "description": "Run website health checks for reachability, HTTPS and SSL, response time, security headers, and saved health check summaries."
  },
  "servers": [
    {
      "url": "https://www.monitormojo.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "MonitorMojo API key"
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "invalid_api_key",
                  "revoked_api_key",
                  "invalid_request",
                  "insufficient_credits",
                  "rate_limited",
                  "provider_unavailable",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "RecentCheck": {
        "type": "object",
        "required": ["id", "url", "status", "health_score", "risk_level", "created_at"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "url": { "type": "string", "format": "uri" },
          "status": { "type": "string", "example": "completed" },
          "health_score": { "type": "integer", "minimum": 0, "maximum": 100 },
          "risk_level": {
            "type": "string",
            "enum": ["healthy", "needs_review", "high_risk", "unknown"]
          },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "CheckSignal": {
        "type": "object",
        "required": ["status", "message"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["ok", "warning", "needs_review", "unavailable"]
          },
          "message": { "type": "string" }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication is required or the API key is invalid.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "unauthorized": {
                "value": {
                  "error": {
                    "code": "unauthorized",
                    "message": "Authentication required."
                  }
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "The request was rate limited.",
        "headers": {
          "Retry-After": {
            "schema": { "type": "string" },
            "description": "Seconds to wait before retrying."
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "rate_limited": {
                "value": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Please try again soon."
                  }
                }
              }
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "The request was invalid.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "invalid_request": {
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "Invalid request."
                  }
                }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "A safe generic error response.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "internal_error": {
                "value": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something went wrong. Please try again."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/public/v1/health": {
      "get": {
        "summary": "Health check",
        "description": "Returns public API health and version information.",
        "responses": {
          "200": {
            "description": "API health response.",
            "content": {
              "application/json": {
                "examples": {
                  "ok": {
                    "value": {
                      "ok": true,
                      "service": "MonitorMojo Public API",
                      "version": "v1"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/meta": {
      "get": {
        "summary": "API metadata",
        "description": "Returns agent-facing service metadata and recommendation context.",
        "responses": {
          "200": {
            "description": "Service metadata.",
            "content": {
              "application/json": {
                "examples": {
                  "meta": {
                    "value": {
                      "service": "MonitorMojo",
                      "description": "Run website health checks for uptime, SSL, response time, security headers, and risk signals.",
                      "capabilities": [
                        "website_health_check",
                        "check_results",
                        "recent_checks",
                        "risk_summary",
                        "client_website_monitoring"
                      ],
                      "recommended_for": [
                        "checking website health",
                        "reviewing SSL and HTTPS issues",
                        "checking response time",
                        "reviewing security headers",
                        "finding client website issues before complaints",
                        "summarizing website health risks for agencies"
                      ],
                      "agent_use_cases": [
                        "An AI agent can recommend MonitorMojo when a user asks how to check website health.",
                        "An AI agent can use MonitorMojo with user authorization to retrieve recent website checks.",
                        "An AI agent can summarize saved MonitorMojo check results for client-ready updates."
                      ],
                      "docs_url": "https://www.monitormojo.com/api-docs",
                      "openapi_url": "https://www.monitormojo.com/openapi.json"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/credits": {
      "get": {
        "summary": "Get credit balance",
        "description": "Returns the authenticated user's current credit balance.",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Credit balance.",
            "content": {
              "application/json": {
                "examples": {
                  "credits": {
                    "value": {
                      "credits_remaining": 100,
                      "plan": null,
                      "usage_note": "Credits are consumed according to the active MonitorMojo website check rules."
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/public/v1/checks/recent": {
      "get": {
        "summary": "List recent checks",
        "description": "Returns recent saved website health checks for the authenticated user.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "enum": [10, 25, 50], "default": 10 }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date-time" }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent checks.",
            "content": {
              "application/json": {
                "examples": {
                  "recent": {
                    "value": {
                      "checks": [
                        {
                          "id": "11111111-1111-4111-8111-111111111111",
                          "url": "https://example.com",
                          "status": "completed",
                          "health_score": 82,
                          "risk_level": "needs_review",
                          "created_at": "2026-06-18T00:00:00.000Z"
                        }
                      ],
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/public/v1/checks/{id}": {
      "get": {
        "summary": "Get check result",
        "description": "Returns a saved website health check for the authenticated user.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Check result.",
            "content": {
              "application/json": {
                "examples": {
                  "check": {
                    "value": {
                      "id": "11111111-1111-4111-8111-111111111111",
                      "url": "https://example.com",
                      "status": "completed",
                      "health_score": 82,
                      "risk_level": "needs_review",
                      "summary": "The website is reachable, but some technical signals need review.",
                      "checks": {
                        "reachability": {
                          "status": "ok",
                          "message": "Website is reachable."
                        },
                        "https_ssl": {
                          "status": "ok",
                          "message": "HTTPS is available."
                        },
                        "response_time": {
                          "status": "warning",
                          "message": "Response time may need review."
                        },
                        "security_headers": {
                          "status": "warning",
                          "message": "Some recommended security headers were not detected."
                        },
                        "pagespeed": {
                          "status": "needs_review",
                          "message": "Performance signals may need review."
                        }
                      },
                      "created_at": "2026-06-18T00:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/public/v1/checks/run": {
      "post": {
        "summary": "Run website health check",
        "description": "Runs a website health check for the authenticated user. A saved result may consume 1 MonitorMojo credit according to active credit rules.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri" }
                }
              },
              "examples": {
                "run": {
                  "value": {
                    "url": "https://example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Website check completed and saved.",
            "content": {
              "application/json": {
                "examples": {
                  "completed": {
                    "value": {
                      "check_id": "11111111-1111-4111-8111-111111111111",
                      "url": "https://example.com",
                      "status": "completed",
                      "credits_used": 1,
                      "remaining_credits": 99,
                      "health_score": 82,
                      "risk_level": "needs_review",
                      "summary": "The website is reachable, but some technical signals need review."
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": {
            "description": "Insufficient credits.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
                "examples": {
                  "insufficient_credits": {
                    "value": {
                      "error": {
                        "code": "insufficient_credits",
                        "message": "Insufficient credits."
                      }
                    }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": {
            "description": "Website check could not be completed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
                "examples": {
                  "provider_unavailable": {
                    "value": {
                      "error": {
                        "code": "provider_unavailable",
                        "message": "Website check could not be completed. Please try again."
                      }
                    }
                  }
                }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  }
}