{
  "openapi": "3.1.0",
  "info": {
    "title": "SignalGrade API",
    "version": "1.0.0",
    "summary": "Public website citation-readiness scores",
    "description": "SignalGrade scores public website origins with the same seven-check engine as https://gmancreations.com/signalgrade. Returns verified/unverified provenance, coverage, signal details, and the first prioritized fix. Homepage HTML checks stay unverified unless the body looks like HTML, so an incomplete read is never presented as a complete /100 grade. No authentication. Payment and private brief endpoints are not part of this API.",
    "contact": {
      "name": "Gman Creations",
      "email": "shoh@gmancreations.com",
      "url": "https://gmancreations.com/developers"
    },
    "license": {
      "name": "Use of this public diagnostic API",
      "url": "https://gmancreations.com/developers"
    }
  },
  "externalDocs": {
    "description": "Connector setup and safety semantics",
    "url": "https://gmancreations.com/developers"
  },
  "servers": [
    {
      "url": "https://gmancreations.com",
      "description": "Production"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Score",
      "description": "Run the public SignalGrade diagnostic on one website origin."
    },
    {
      "name": "Meta",
      "description": "Machine-readable description of this API."
    }
  ],
  "paths": {
    "/api/v1/score": {
      "get": {
        "operationId": "scoreWebsiteGet",
        "tags": ["Score"],
        "summary": "Score a public website (GET)",
        "description": "Fetch the origin homepage, /robots.txt, and /llms.txt, then score them with evaluateSignals. Query parameter url is the public website. Optional name is a label. Returns schema signalgrade.score.v1. If htmlVerified is false, score.complete is false, score.outOf is null, and the readout is verified coverage (for example 14 / 26 verified points), not a /100 grade.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Public website to score. Paths are ignored; the origin homepage is scored, same as the live scorecard.",
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 2048,
              "examples": ["https://example.com"]
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Optional business or page label. Defaults to the hostname.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Diagnostic result. Check provenance.htmlVerified and score.complete before treating value as a full /100 score.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScoreResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid or forbidden url (private, internal, IP, unsafe protocol, or unresolved host).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "413": {
            "description": "POST body larger than 8KB.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Per-instance rate limit exceeded. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Scoring failed after a valid public url was accepted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "scoreWebsitePost",
        "tags": ["Score"],
        "summary": "Score a public website (POST)",
        "description": "Same scoring path as scoreWebsiteGet. JSON body: {\"url\":\"https://example.com\",\"name\":\"Optional label\"}. Body size cap is 8KB. No authentication. Only url and optional name are read.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ScoreRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diagnostic result. Unverified HTML is never a complete /100 grade.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScoreResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing url, or forbidden target.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "413": {
            "description": "POST body larger than 8KB.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Per-instance rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Scoring failed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "tags": ["Meta"],
        "summary": "OpenAPI 3.1 document",
        "description": "Canonical machine-readable description of the deployed SignalGrade API. Use this URL when creating a Muse custom connector.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 JSON document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScoreRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "description": "Public website. Paths are ignored; the origin homepage is scored.",
            "examples": ["https://example.com"]
          },
          "name": {
            "type": "string",
            "description": "Optional label. Defaults to the hostname.",
            "maxLength": 120
          }
        }
      },
      "ScoreResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["schema", "ok", "url", "provenance", "coverage", "score", "signals", "firstFix", "disclaimer"],
        "properties": {
          "schema": {
            "type": "string",
            "const": "signalgrade.score.v1"
          },
          "ok": {
            "type": "boolean",
            "const": true
          },
          "url": {
            "type": "string",
            "description": "Normalized origin that was scored."
          },
          "name": {
            "type": "string"
          },
          "provenance": { "$ref": "#/components/schemas/Provenance" },
          "coverage": { "$ref": "#/components/schemas/Coverage" },
          "score": { "$ref": "#/components/schemas/ScoreReadout" },
          "signals": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Signal" }
          },
          "firstFix": {
            "oneOf": [
              { "$ref": "#/components/schemas/Fix" },
              { "type": "null" }
            ]
          },
          "priorityFixes": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Fix" }
          },
          "summary": {
            "type": "string"
          },
          "disclaimer": {
            "type": "string"
          }
        }
      },
      "Provenance": {
        "type": "object",
        "required": ["htmlVerified", "htmlFetched", "sourceFormat", "label"],
        "properties": {
          "htmlVerified": {
            "type": "boolean",
            "description": "True only when the homepage body looks like HTML."
          },
          "htmlFetched": {
            "type": "boolean"
          },
          "htmlReader": {
            "type": ["string", "null"],
            "description": "origin for a direct read, jina for the Markdown fallback, or null."
          },
          "sourceFormat": {
            "type": ["string", "null"],
            "enum": ["html", "markdown", "unknown", "empty", null]
          },
          "label": {
            "type": "string",
            "description": "Human provenance line, matching the live scorecard."
          }
        }
      },
      "Coverage": {
        "type": "object",
        "required": ["complete", "verifiedEarned", "verifiedPoints", "unverifiedPoints", "totalPoints"],
        "properties": {
          "complete": { "type": "boolean" },
          "verifiedEarned": { "type": "integer" },
          "verifiedPoints": { "type": "integer" },
          "unverifiedPoints": { "type": "integer" },
          "totalPoints": { "type": "integer", "description": "Always 100 for the seven-check instrument." }
        }
      },
      "ScoreReadout": {
        "type": "object",
        "required": ["complete", "display", "primary", "secondary", "note", "value", "grade", "outOf"],
        "properties": {
          "complete": {
            "type": "boolean",
            "description": "False when any check is unverified. Then outOf is null and display is verified coverage, not /100."
          },
          "display": { "type": "string" },
          "primary": { "type": "string" },
          "secondary": { "type": "string" },
          "note": { "type": "string" },
          "value": { "type": "integer", "description": "Verified points earned. Not a /100 grade unless complete is true." },
          "grade": {
            "type": ["string", "null"]
          },
          "outOf": {
            "type": ["integer", "null"],
            "description": "100 only when complete is true."
          }
        }
      },
      "Signal": {
        "type": "object",
        "required": ["key", "label", "state", "detail", "earned", "points"],
        "properties": {
          "key": { "type": "string" },
          "label": { "type": "string" },
          "state": {
            "type": "string",
            "enum": ["pass", "warn", "fail", "unverified"]
          },
          "detail": { "type": "string" },
          "earned": { "type": "integer" },
          "points": { "type": "integer" },
          "fix": { "type": "string" }
        }
      },
      "Fix": {
        "type": "object",
        "required": ["label", "fix"],
        "properties": {
          "key": { "type": ["string", "null"] },
          "label": { "type": "string" },
          "state": { "type": ["string", "null"] },
          "fix": { "type": "string" },
          "earned": { "type": ["integer", "null"] },
          "points": { "type": ["integer", "null"] }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["schema", "ok", "error"],
        "properties": {
          "schema": {
            "type": "string",
            "const": "signalgrade.score.v1"
          },
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_url",
                  "forbidden_target",
                  "unresolved_host",
                  "bad_request",
                  "method_not_allowed",
                  "payload_too_large",
                  "rate_limited",
                  "score_failed"
                ]
              },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}