x402.professorsausages.com

{
  "properties": {
    "articles": {
      "description": "The matched articles themselves (title + url, newest first, capped at 50) — so a timeline hit is reachable, not just a count.",
      "items": {
        "properties": {
          "also": {
            "description": "Up to 3 OTHER outlets telling this story (distinct domains, most trusted/largest source first — see `source_score` — then earliest); [] when none.",
            "items": {
              "properties": {
                "domain": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "domain",
                "url"
              ],
              "type": "object"
            },
            "maxItems": 3,
            "type": "array"
          },
          "author": {
            "description": "Byline as the feed states it (dc:creator/author; `hn:<user>` for Hacker News). null when absent.",
            "type": [
              "string",
              "null"
            ]
          },
          "categories": {
            "description": "Categories from the feed's section, the publisher's URL path, and title/summary anchors — assigned at ingest (an article can carry several).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "cluster": {
            "description": "EXACT title-set id — articles sharing one carry the same headline words. The served window keeps one article per exact id; near-duplicates in other words are grouped by `cluster_id`. null when the headline was too short to cluster safely.",
            "type": [
              "string",
              "null"
            ]
          },
          "cluster_id": {
            "description": "Story id: records sharing it are the SAME story told by different outlets, even in different words (near-duplicate headlines within 48h). It is the id of the story's earliest copy; a singleton's is its own id. Tapes show one record per story. Absent on archive-shard records (/search, /timeline).",
            "type": "string"
          },
          "cluster_size": {
            "description": "Records in the served window telling this story (1 = only this outlet).",
            "minimum": 1,
            "type": "integer"
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "domain": {
            "type": "string"
          },
          "feed": {
            "description": "Human feed label, e.g. \"BBC World\", \"Hacker News\", \"GDELT 15-min files\".",
            "type": "string"
          },
          "id": {
            "description": "sha1(normalized url) hex, first 16 chars — the dedupe key.",
            "type": "string"
          },
          "image": {
            "description": "Lead image URL from the feed (media:content/thumbnail/enclosure/news image). null when absent.",
            "type": [
              "string",
              "null"
            ]
          },
          "lang": {
            "description": "ISO-639-1 language, best-effort.",
            "type": [
              "string",
              "null"
            ]
          },
          "published": {
            "description": "ISO-8601 publish time (best-effort).",
            "type": "string"
          },
          "seen_at": {
            "type": "string"
          },
          "snippet": {
            "description": "Short plain-text description from the feed (≤240 chars); absent when the feed carries none. `summary` is the longer form.",
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "enum": [
              "gdelt",
              "hn",
              "rss",
              "gnews",
              "sitemap"
            ],
            "type": "string"
          },
          "source_score": {
            "description": "Trust + scale of this record's SOURCE, 0–1. Editorial trust class first (wire agencies > major outlets > primary institutions > established trade/regional > unknown > press-release wires & corporate newsrooms > aggregators/syndicators), then the source's measured volume and feed breadth in our corpus. A tape shows the highest-scoring copy of a story (its lead), so a press-release copy leads only when no editorial outlet carries the story. Not a quality verdict on the article itself. Absent on archive-shard records (/search, /timeline).",
            "example": 0.957,
            "maximum": 1,
            "minimum": 0,
            "type": "number"
          },
          "summary": {
            "description": "The feed's own description, plain text, ≤400 chars. null when the feed carries none.",
            "type": [
              "string",
              "null"
            ]
          },
          "tier": {
            "description": "Reputability tier of the feed: official (primary sources — government/central-bank/agency press and first-party lab/vendor newsrooms), major (wires + major outlets), trade (quality trade press), social (Hacker News), enrichment (GDELT-discovered, reputation-gated). Absent on records archived before the tiered portfolio.",
            "enum": [
              "official",
              "major",
              "trade",
              "social",
              "enrichment",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": "string"
          },
          "tone": {
            "description": "Sentiment on GDELT's scale (negative = adverse, roughly −10..+10). READ tone_method: gdelt = whole-document tone attached by URL match; lexicon = our local headline+summary lexicon. null when neither could score it.",
            "type": [
              "number",
              "null"
            ]
          },
          "tone_confidence": {
            "description": "How much to trust `tone`. high: GDELT document tone matched on the canonical URL. medium: GDELT tone matched loosely (host + path), or the lexicon over title + summary with ≥2 hits. low: the lexicon over a headline alone or a single hit. null: no tone. Absent on records written before 2026-09-20.",
            "enum": [
              "high",
              "medium",
              "low",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "tone_method": {
            "description": "How `tone` was produced. gdelt: GDELT document tone (GKG V1.5TONE / events AvgTone) matched by canonical URL — whole-article, the strongest. lexicon: our local lexicon over title + summary — coarse, headline-scale; replaced by a GDELT tone the moment one arrives. null: no tone could be computed. Absent on records archived before 2026-09 (their tone, if any, is GDELT's).",
            "enum": [
              "gdelt",
              "lexicon",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string"
          },
          "via": {
            "description": "Relay provenance: the social account or newsletter that pointed us at this article (e.g. \"@eff@mastodon.social\", \"bsky:reuters.com\"). Present only on `source: push:*` records — the record is still the LINKED publisher's article, and `via` is who relayed it, never the byline.",
            "type": [
              "string",
              "null"
            ]
          },
          "word_count": {
            "description": "Article body word count: GDELT's GKG count when it saw the document, else a full-text feed body's count. null when only a teaser was available — never estimated.",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "url",
          "domain",
          "source",
          "feed",
          "published",
          "categories",
          "seen_at"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "bucket": {
      "enum": [
        "hour",
        "day"
      ],
      "type": "string"
    },
    "buckets": {
      "items": {
        "properties": {
          "avg_tone": {
            "description": "Mean tone of the bucket's SCORED articles (tone_n of count), or null when tone_n is 0 — never a silent zero.",
            "type": [
              "number",
              "null"
            ]
          },
          "count": {
            "type": "integer"
          },
          "t": {
            "description": "Bucket start (ISO date or ISO hour).",
            "type": "string"
          },
          "tone_methods": {
            "description": "Provenance split of the scored articles in this bucket.",
            "properties": {
              "gdelt": {
                "type": "integer"
              },
              "lexicon": {
                "type": "integer"
              }
            },
            "type": "object"
          },
          "tone_n": {
            "description": "How many of the bucket's articles carried a tone.",
            "type": "integer"
          }
        },
        "required": [
          "t",
          "count",
          "avg_tone",
          "tone_n",
          "tone_methods"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "depth": {
      "properties": {
        "days_available": {
          "description": "Day shards retained in the index.",
          "type": "integer"
        },
        "days_scanned": {
          "description": "Day shards read for this response.",
          "type": "integer"
        },
        "mode": {
          "description": "archive = publish-day shards were fanned over; snapshot = served-window fallback (no archive index yet).",
          "enum": [
            "archive",
            "snapshot"
          ],
          "type": "string"
        },
        "newest_day": {
          "type": [
            "string",
            "null"
          ]
        },
        "oldest_day": {
          "type": [
            "string",
            "null"
          ]
        },
        "truncated": {
          "description": "True when the requested range held more days than one request may scan — narrow from/to to reach the rest.",
          "type": "boolean"
        }
      },
      "required": [
        "mode",
        "days_scanned",
        "days_available",
        "truncated"
      ],
      "type": "object"
    },
    "freshness": {
      "properties": {
        "as_of": {
          "description": "updated_at of the corpus this response was served from.",
          "type": "string"
        },
        "coverage": {
          "properties": {
            "articles": {
              "description": "Articles covering that span.",
              "type": "integer"
            },
            "hours": {
              "description": "newest − oldest in hours — the searchable depth. On the tapes it is ~window_hours (the refresh fails its audit when it falls more than 1h short); on /search and /timeline it is what the scanned shards spanned.",
              "type": "number"
            },
            "newest_published": {
              "description": "Newest publish time held.",
              "type": [
                "string",
                "null"
              ]
            },
            "oldest_published": {
              "description": "Oldest publish time held; the real floor of any date filter.",
              "type": [
                "string",
                "null"
              ]
            },
            "thin": {
              "description": "Hot-window routes only: true when fewer than 5 articles matched your filter in the served window. The answer is still complete and paid — `why` says what was checked and where more lives (/news/search reaches the multi-day archive).",
              "type": "boolean"
            },
            "why": {
              "description": "Present when thin: which filter was applied, how many articles matched, which portfolio feeds carry that category.",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "oldest_published",
            "newest_published",
            "hours",
            "articles"
          ],
          "type": "object"
        },
        "source_count": {
          "description": "Number of ingestion sources (rss/sitemap/hn/gdelt/gnews) with ≥1 article in the current pile.",
          "type": "integer"
        },
        "window_hours": {
          "description": "Retention POLICY in hours (72) — the span the tapes hold, audited against the measured coverage.hours (which is what to trust for time-range work).",
          "type": "integer"
        }
      },
      "required": [
        "as_of",
        "window_hours",
        "source_count",
        "coverage"
      ],
      "type": "object"
    },
    "poll": {
      "properties": {
        "next_cursor": {
          "description": "Opaque cursor (prefix `nc1.`) marking the newest article this answer could see — pass as `since` next time. Null only on an empty corpus.",
          "type": [
            "string",
            "null"
          ]
        },
        "note": {
          "description": "How this page relates to your `since` (ingest-order walk, whether more remain).",
          "type": "string"
        },
        "suggested_interval_seconds": {
          "description": "How often to poll (900: the corpus refreshes every 15 minutes).",
          "type": "integer"
        },
        "updated_at": {
          "description": "The corpus refresh this answer was served from.",
          "type": "string"
        }
      },
      "required": [
        "next_cursor",
        "suggested_interval_seconds",
        "updated_at"
      ],
      "type": "object"
    },
    "query": {
      "description": "Your `q` echoed back, or null when you omitted it (every article in the scanned span is then bucketed).",
      "type": [
        "string",
        "null"
      ]
    },
    "returned": {
      "description": "How many matched articles are included in `articles` (capped at 50).",
      "type": "integer"
    },
    "terms": {
      "additionalProperties": {
        "type": "integer"
      },
      "description": "How many articles contain each individual query term/phrase — explains why an AND of several terms returns few/none.",
      "type": "object"
    },
    "tone": {
      "properties": {
        "gdelt": {
          "description": "Scored via GDELT document tone.",
          "type": "integer"
        },
        "lexicon": {
          "description": "Scored via the local lexicon.",
          "type": "integer"
        },
        "method": {
          "description": "What avg_tone is made of overall: gdelt only, lexicon only, mixed, or null when nothing was scored.",
          "enum": [
            "gdelt",
            "lexicon",
            "mixed",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "note": {
          "type": "string"
        },
        "scored": {
          "description": "Matched articles with a tone (any provenance).",
          "type": "integer"
        },
        "unscored": {
          "description": "Matched articles with no tone — they are counted in `buckets[].count` but not in any avg_tone.",
          "type": "integer"
        }
      },
      "required": [
        "scored",
        "unscored",
        "gdelt",
        "lexicon",
        "method"
      ],
      "type": "object"
    },
    "total": {
      "description": "Total matched articles (the true count the buckets sum to).",
      "type": "integer"
    }
  },
  "required": [
    "query",
    "bucket",
    "total",
    "returned",
    "buckets",
    "articles",
    "terms",
    "tone",
    "freshness"
  ],
  "type": "object"
}