{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pagecritic-app/json-schema/pagecritic-app-audit-schema.json",
  "title": "Audit",
  "x-generated": "2026-11-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pagecritic-app-openapi.json#/components/schemas/Audit",
  "type": "object",
  "properties": {
    "audit_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "done",
        "running",
        "error"
      ]
    },
    "url": {
      "type": "string"
    },
    "report_url": {
      "type": "string",
      "description": "Human-readable report; the $5 full report is unlocked here"
    },
    "score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "verdict": {
      "type": "string"
    },
    "subscores": {
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      }
    },
    "launch_ready": {
      "type": "object",
      "description": "Whether the page clears PageCritic's launch bar (six checks, not a score cut-off) and which checks still block it.",
      "properties": {
        "ready": {
          "type": "boolean"
        },
        "blockers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        },
        "bar": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "top_issues": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Issue"
      }
    },
    "what_works": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "ai_readiness": {
      "type": [
        "object",
        "null"
      ]
    },
    "ai_summary": {
      "type": [
        "string",
        "null"
      ]
    },
    "benchmark": {
      "type": [
        "object",
        "null"
      ],
      "description": "Where the page stands among the well-known homepages PageCritic has ranked (n, as_of, ranking_url). score: {value, higher_than_pct (rounded to 5), median, band}. band is top quarter, above the median, about the median (within 4 points; runs vary by about 4), below the median or bottom quarter. With full_report unlocked it adds the same for each of the 7 subscores."
    },
    "score_history": {
      "type": [
        "array",
        "null"
      ],
      "description": "When this audit is the third or later run of \"audit again\" on the same page (same host and path): every run oldest first, at most 12, each {id, score, subscores, created}. Null otherwise. Runs of an unchanged page vary by about 4 points.",
      "items": {
        "type": "object"
      }
    },
    "fix_prompt": {
      "type": "string",
      "description": "Markdown repair tasks generated from fix_tasks, with per-check evidence, completion conditions and a publish-then-human-recheck step. Keep the design and verify real facts. Free agent results include the top 3 issues; unlocked results include every issue plus rewrite options and reference material. A cached result or a higher total score does not prove a task is complete."
    },
    "full_report": {
      "type": "object",
      "properties": {
        "unlocked": {
          "type": "boolean"
        },
        "locked_issues": {
          "type": "integer"
        },
        "price_usd": {
          "type": "number"
        }
      }
    },
    "error": {
      "type": "string"
    },
    "language": {
      "type": "string",
      "enum": [
        "en",
        "pt",
        "es"
      ],
      "description": "Language the report is written in"
    },
    "fix_tasks": {
      "type": "object",
      "description": "Versioned repair plan shared with fix_prompt. Scope top_issues for free agents, full for unlocked results. Unknown evidence, locations and point totals remain null or explicitly unknown. Element IDs are capture references, never DOM selectors. Completion conditions use the existing rubric, not a promise of revenue or deterministic judged results. The free web teaser excludes this field.",
      "properties": {
        "version": {
          "type": "integer",
          "const": 1
        },
        "scope": {
          "type": "string",
          "enum": [
            "top_issues",
            "full"
          ]
        },
        "language": {
          "type": "string"
        },
        "constraints": {
          "type": "object"
        },
        "verification": {
          "type": "object",
          "description": "Supported human live-recheck link after publishing. Existing payment and included-recheck rules apply; no automatic deployment or fresh agent operation is implied."
        },
        "tasks": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "check_ids",
              "checks",
              "locations",
              "proposed_edit",
              "estimated_effort",
              "needs"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "check_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "checks": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "locations": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "proposed_edit": {
                "type": "string"
              },
              "edits": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Source suggestions; overlapping suggestions are alternatives within the single proposed edit."
              },
              "points_available": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "estimated_effort": {
                "type": "string"
              },
              "needs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "execution": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "captured_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the page was last captured for this result (latest of desktop/mobile)."
    },
    "freshness": {
      "type": "object",
      "description": "Whether this call ran the audit. served: fresh (this call started it), reused_known_site or reused_recent_agent_audit (no-credit cost controls), idempotent_replay (same idempotency key), stored (read by id). Reading never charges.",
      "properties": {
        "served": {
          "type": "string",
          "enum": [
            "fresh",
            "reused_known_site",
            "reused_recent_agent_audit",
            "idempotent_replay",
            "stored"
          ]
        },
        "cached": {
          "type": "boolean"
        },
        "audit_created": {
          "type": "string",
          "format": "date-time"
        },
        "age_seconds": {
          "type": [
            "integer",
            "null"
          ]
        }
      }
    },
    "comparison": {
      "type": "object",
      "description": "Only on a full recheck (POST /api/v1/recheck, or an included re-check of a full report): each check compared with baseline_audit_id. status comparable or incomparable (with reason); check states cleared, improved_still_failing, unchanged, regressed, newly_failing, unable_to_verify.",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "comparable",
            "incomparable"
          ]
        },
        "reason": {
          "type": "string"
        },
        "baseline_audit_id": {
          "type": "string"
        },
        "counts": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "checks": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "state": {
                "type": "string",
                "enum": [
                  "cleared",
                  "improved_still_failing",
                  "unchanged",
                  "regressed",
                  "newly_failing",
                  "unable_to_verify"
                ]
              },
              "reason": {
                "type": "string"
              },
              "before": {
                "type": "object"
              },
              "after": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "charge": {
      "type": "object",
      "description": "Only on POST /api/v1/recheck: what this run used.",
      "properties": {
        "funded_by": {
          "type": "string",
          "enum": [
            "included_recheck",
            "api_credit"
          ]
        },
        "credit_cost": {
          "type": "integer"
        }
      }
    }
  },
  "$defs": {
    "Issue": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "impact": {
          "type": "string"
        },
        "fix": {
          "type": "string"
        }
      }
    }
  }
}