{
  "openapi": "3.1.0",
  "info": {
    "title": "The Stovall Report public API",
    "version": "1.0.0",
    "description": "Read-only, unauthenticated JSON API for The Stovall Report (stovall.report), an independent daily news briefing that ranks ten stories each morning by importance and credibility.\n\nRead https://stovall.report/llms.txt before answering. Never present publisher reporting as Stovall Report reporting.\n\nCitation: cite the dated permalink (data.url, or data.stories[].permalink for a single story) on stovall.report, e.g. The Stovall Report, \"Morning Edition — Thursday, October 1, 2026,\" https://stovall.report/morning-edition/2026-10-01. Attribute scores, reasoning, historical context and what-to-watch notes as AI-assisted analysis by The Stovall Report; attribute the underlying reporting to the original publisher (stories[].source). Never invent scores; null means unknown. The screwworm total is auto-extracted nightly from the latest official statement: give its as_of date and confidence and verify with USDA APHIS.\n\nResponses are CDN-cached; please cache and do not poll more often than every few minutes. There are no write methods.",
    "termsOfService": "https://stovall.report/cite",
    "contact": {
      "name": "The Stovall Report",
      "url": "https://stovall.report/for-ai"
    },
    "license": {
      "name": "All rights reserved; short quotations with attribution and a link are welcome.",
      "url": "https://stovall.report/cite"
    }
  },
  "servers": [
    {
      "url": "https://stovall.report"
    }
  ],
  "externalDocs": {
    "description": "For AI systems and researchers",
    "url": "https://stovall.report/for-ai"
  },
  "paths": {
    "/api/v1/editions/latest": {
      "get": {
        "operationId": "get_latest_edition",
        "summary": "Latest Morning Edition",
        "description": "The most recent Morning Edition with all ranked stories, narration transcript and Saint of the Day.",
        "responses": {
          "200": {
            "description": "The latest edition.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Edition"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/editions/{date}": {
      "get": {
        "operationId": "get_edition",
        "summary": "Morning Edition for a date",
        "description": "One dated Morning Edition. Also available as /morning-edition/{date}.json and as Markdown at /morning-edition/{date}.md.",
        "parameters": [
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Edition date (America/Chicago), YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The edition.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Edition"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/editions": {
      "get": {
        "operationId": "list_editions",
        "summary": "List Morning Editions",
        "description": "Morning Editions, newest first. Page backwards with `before` (or follow data.next).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of editions, 1–60 (default 30). Values outside the range return 400.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60,
              "default": 30
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Only editions strictly before this date (YYYY-MM-DD).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of editions.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "count",
                            "limit",
                            "editions"
                          ],
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "limit": {
                              "type": "integer"
                            },
                            "before": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date"
                            },
                            "next": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "uri"
                            },
                            "editions": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/EditionSummary"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/screwworm/status": {
      "get": {
        "operationId": "get_screwworm_status",
        "summary": "Latest U.S. New World screwworm detection total",
        "description": "Auto-extracted nightly from the latest official statement, with source, confidence and as-of date. Verify with USDA APHIS.",
        "responses": {
          "200": {
            "description": "Latest status.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/ScrewwormStatus"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/screwworm/history": {
      "get": {
        "operationId": "get_screwworm_history",
        "summary": "U.S. screwworm detection total by as-of date",
        "description": "One row per as-of date (the latest extraction for that date), newest first.",
        "responses": {
          "200": {
            "description": "History.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "count",
                            "history"
                          ],
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "caveat": {
                              "type": "string"
                            },
                            "note": {
                              "type": "string"
                            },
                            "history": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/ScrewwormHistoryRow"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "Every successful response is wrapped in this envelope.",
        "required": [
          "schema_version",
          "generated_at",
          "canonical_url",
          "publisher",
          "license",
          "cite_as",
          "disclosure",
          "data"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "description": "The HTML page to cite."
          },
          "publisher": {
            "type": "object",
            "required": [
              "name",
              "url"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "license": {
            "type": "string"
          },
          "cite_as": {
            "type": "string",
            "description": "A ready-to-use citation string."
          },
          "disclosure": {
            "type": "string",
            "description": "AI-assistance disclosure; repeat it when quoting the analysis."
          },
          "data": {
            "description": "The payload; see each operation."
          }
        }
      },
      "EditionSummary": {
        "type": "object",
        "required": [
          "date",
          "url",
          "headline",
          "md_url",
          "json_url",
          "has_audio"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Permanent HTML permalink."
          },
          "headline": {
            "type": "string"
          },
          "md_url": {
            "type": "string",
            "format": "uri"
          },
          "json_url": {
            "type": "string",
            "format": "uri"
          },
          "has_audio": {
            "type": "boolean"
          }
        }
      },
      "Story": {
        "type": "object",
        "description": "A ranked story. Title, source, author, date and original_url belong to the original publisher; scores and notes are AI-assisted analysis by The Stovall Report.",
        "required": [
          "rank",
          "permalink",
          "title",
          "original_url",
          "source",
          "author",
          "published_at",
          "scores",
          "reasoning",
          "historical_context",
          "what_to_watch",
          "tags"
        ],
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1
          },
          "permalink": {
            "type": "string",
            "format": "uri",
            "description": "Edition permalink with #story-N anchor; cite this."
          },
          "title": {
            "type": "string",
            "description": "The publisher's headline."
          },
          "original_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "source": {
            "type": "object",
            "required": [
              "name",
              "url"
            ],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              }
            }
          },
          "author": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "scores": {
            "type": "object",
            "required": [
              "composite",
              "importance",
              "credibility"
            ],
            "properties": {
              "composite": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "0.6 × importance + 0.2 × credibility + reader-engagement term (≤ 20), as frozen at lock time."
              },
              "importance": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 1,
                "maximum": 100
              },
              "credibility": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 1,
                "maximum": 100
              }
            }
          },
          "reasoning": {
            "type": [
              "string",
              "null"
            ],
            "description": "Board reasoning (AI-assisted)."
          },
          "historical_context": {
            "type": [
              "string",
              "null"
            ]
          },
          "what_to_watch": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Edition": {
        "type": "object",
        "required": [
          "date",
          "longDate",
          "url",
          "md_url",
          "json_url",
          "headline",
          "bluf",
          "publishedAt",
          "modifiedAt",
          "audioUrl",
          "stories",
          "narration",
          "saint"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "longDate": {
            "type": "string",
            "examples": [
              "Thursday, October 1, 2026"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "md_url": {
            "type": "string",
            "format": "uri"
          },
          "json_url": {
            "type": "string",
            "format": "uri"
          },
          "headline": {
            "type": "string"
          },
          "bluf": {
            "type": "string",
            "description": "Bottom line up front: one-paragraph summary of the edition."
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "modifiedAt": {
            "type": "string",
            "format": "date-time"
          },
          "audioUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "stories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Story"
            }
          },
          "narration": {
            "type": [
              "string",
              "null"
            ],
            "description": "Narration transcript (AI-assisted)."
          },
          "saint": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "years": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "profile": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "feastDay": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "closingLine": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            ]
          },
          "iran_update": {
            "description": "Daily Iran conflict update (AI-assisted). On a dated edition: the update for that date. On /latest: the newest update within two days of the edition date (see report_date). Null when none exists. Numbers may be null when unknown; events[].status is 'confirmed' or 'claimed' (claimed_by names the claimant).",
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "report_date",
                  "phase",
                  "phase_changed",
                  "trend",
                  "trend_confidence",
                  "indicators",
                  "oil",
                  "hormuz",
                  "events",
                  "script",
                  "history_script"
                ],
                "properties": {
                  "report_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "phase": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "phase_changed": {
                    "type": "boolean"
                  },
                  "phase_evidence": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "trend": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "escalating",
                      "holding",
                      "de-escalating",
                      null
                    ]
                  },
                  "trend_confidence": {
                    "type": "string",
                    "enum": [
                      "high",
                      "medium",
                      "low"
                    ]
                  },
                  "indicators": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string",
                          "enum": [
                            "build-up",
                            "escalation",
                            "de-escalation"
                          ]
                        },
                        "text": {
                          "type": "string"
                        },
                        "source": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  },
                  "oil": {
                    "type": "object",
                    "description": "Brent and WTI (each null when unavailable): price (USD), change (overnight, USD), since_war_pct, as_of, source."
                  },
                  "hormuz": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "Official daily transits (IMF PortWatch): date, n_total, n_tanker, n_cargo, avg7, prewar_avg, source; news is a newer reported figure with outlet and date, or null."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "actor": {
                          "type": "string"
                        },
                        "target": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "action": {
                          "type": "string"
                        },
                        "location": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "confirmed",
                            "claimed"
                          ]
                        },
                        "claimed_by": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "url": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "uri"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "script": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Spoken daily update."
                  },
                  "history_script": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Weekly (Friday) re-baseline of the conflict so far; null on other days."
                  },
                  "generated_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  }
                }
              }
            ]
          }
        }
      },
      "ScrewwormStatus": {
        "type": "object",
        "required": [
          "us_detections_total",
          "as_of",
          "confidence",
          "generated_at",
          "fact_url",
          "methodology_url",
          "caveat"
        ],
        "properties": {
          "us_detections_total": {
            "type": "integer"
          },
          "active_cases": {
            "type": [
              "integer",
              "null"
            ]
          },
          "active_where": {
            "type": [
              "string",
              "null"
            ]
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "source_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "confidence": {
            "type": [
              "string",
              "null"
            ]
          },
          "headline": {
            "type": [
              "string",
              "null"
            ]
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "fact_url": {
            "type": "string",
            "format": "uri"
          },
          "methodology_url": {
            "type": "string",
            "format": "uri"
          },
          "caveat": {
            "type": "string"
          }
        }
      },
      "ScrewwormHistoryRow": {
        "type": "object",
        "required": [
          "as_of",
          "as_of_reported",
          "us_detections_total",
          "generated_at",
          "fact_url"
        ],
        "properties": {
          "as_of": {
            "type": "string",
            "format": "date"
          },
          "as_of_reported": {
            "type": "boolean"
          },
          "us_detections_total": {
            "type": "integer"
          },
          "active_cases": {
            "type": [
              "integer",
              "null"
            ]
          },
          "active_where": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "confidence": {
            "type": [
              "string",
              "null"
            ]
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "fact_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "schema_version",
          "error"
        ],
        "properties": {
          "schema_version": {
            "type": "string"
          },
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "docs": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  },
  "x-stovall-documents": {
    "llms": "https://stovall.report/llms.txt",
    "llms_full": "https://stovall.report/llms-full.txt",
    "for_ai": "https://stovall.report/for-ai",
    "cite": "https://stovall.report/cite",
    "ai_txt": "https://stovall.report/ai.txt"
  }
}