{
  "openapi": "3.1.0",
  "info": {
    "title": "TruthFoundry - Signed News Record API",
    "version": "1.84.0",
    "description": "A signed, dated record of world events for humans and AI agents, frozen day by day, with rich structured fields per article (entities, signals, events, facts) and Ed25519 provenance throughout. Live corpus scale, by population and window, is published on /health. All /v1/* endpoints take a key via the X-Newsboy-Key header (or Authorization: Bearer). The full record is free to read on the web; the API needs a key (free demo access powers the site, paid tiers at /pricing). TruthFoundry is an open alpha: expect schema additions and visible sync lag on /health."
  },
  "servers": [
    {
      "url": "https://truthfoundry.ai",
      "description": "Live API origin"
    }
  ],
  "tags": [
    {
      "name": "Status",
      "description": "Health and sync state. No key required."
    },
    {
      "name": "Search",
      "description": "Keyword search and retrieve-then-reason cited answers."
    },
    {
      "name": "Articles",
      "description": "Browse, detail, and per-article provenance."
    },
    {
      "name": "Signals",
      "description": "Market-momentum signals and trending topics."
    },
    {
      "name": "Intel",
      "description": "Open public-data feeds (prediction markets, legislation, economic releases)."
    },
    {
      "name": "Graph",
      "description": "The entity / event / fact graph extracted from the record."
    },
    {
      "name": "Digests",
      "description": "Signed, cited briefs by topic, region, and kind."
    },
    {
      "name": "Archive",
      "description": "The frozen, signed daily record and per-publisher pages."
    },
    {
      "name": "Smart Query",
      "description": "Composable, hardened intelligence pipelines. Requires a paid key."
    },
    {
      "name": "Account",
      "description": "Your key's usage and the homepage payload."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Service status, the running version and the record's public totals. No API key required.",
        "tags": [
          "Status"
        ],
        "x-metering": "free",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Keyword search",
        "description": "Full-text and meaning search over the verified record (default), or mode=keyword: every word must match, English by default, the last 30 days, no meaning search. A search that finds nothing is never charged. The TruthFoundry Search plan ($5 a month for 10,000 keyword searches) covers mode=keyword: https://drm3.network/account?checkout=truthfoundry-search-v1&app=truthfoundry",
        "tags": [
          "Search"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search query (keywords or phrase)."
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "keyword"
              ]
            },
            "description": "keyword: every word must match, English unless language= says otherwise (language=all for every language), last 30 days (since= up to 30d), 60 a minute per key."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "30d"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 30d."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows to return. Default 20, cap 100 (server-clamped)."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Pagination offset."
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "ISO language code, e.g. \"en\", \"es\", \"ja\"."
          },
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Topic filter."
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Content-kind filter (comma-separated): news | blog | release_notes | spec | forum_social. Omit for all kinds; an invalid value is a 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/ask": {
      "get": {
        "summary": "Ask (retrieve-then-reason)",
        "description": "A cited, signed answer built by retrieving the relevant record and reasoning over it. Honest empty when there is no verified coverage; never like-worded filler. Pass stream=1 for token streaming.",
        "tags": [
          "Search"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The question."
          },
          {
            "name": "stream",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ]
            },
            "description": "1 to stream tokens."
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Content-kind filter (comma-separated): news | blog | release_notes | spec | forum_social. Omit for all kinds; an invalid value is a 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Cited answer (JSON, or an SSE stream when stream=1)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/factcheck": {
      "get": {
        "summary": "Fact-check a claim against the record",
        "description": "Resolve a claim/headline/question against the signed record by meaning and return what the record HOLDS: coverage, extracted fact lines, the word-for-word publisher claim record, and independent cross-witness instruments, each with receipts. Absence is stated as absence (empty = the record does not carry the claim, not a verdict of false); never a true/false score. instruments=1 returns ONLY the record (fast, unbilled, and served KEYLESS - no key, no 402, per-IP rate limited) for agents; the default adds a grounded written read (metered to the signed-in user); stream=1 streams it.",
        "tags": [
          "Search"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The claim, headline, or question to check."
          },
          {
            "name": "instruments",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ]
            },
            "description": "1 = record instruments only (fast, unbilled, keyless - the agent contract)."
          },
          {
            "name": "stream",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ]
            },
            "description": "1 to stream the written read."
          }
        ],
        "responses": {
          "200": {
            "description": "What the record holds (claim, coverage, facts, claims, witness), plus a written read unless instruments=1."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/articles": {
      "get": {
        "summary": "Browse articles",
        "description": "Recent articles, filterable by topic, category, language, kind, and window.",
        "tags": [
          "Articles"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"business\", \"technology\"."
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "ISO language code, e.g. \"en\", \"es\", \"ja\"."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "24h"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 24h."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows to return. Default 20, cap 100 (server-clamped)."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Pagination offset."
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Content-kind filter (comma-separated): news | blog | release_notes | spec | forum_social. Omit for all kinds; an invalid value is a 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/articles/{id}": {
      "get": {
        "summary": "Article detail",
        "description": "One article with all structured fields. The live (<=7d) window is open to any key incl. the demo key; older articles need a signed-in DRM3 account or a key of your own.",
        "tags": [
          "Articles"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Article"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/articles/{id}/provenance": {
      "get": {
        "summary": "Article provenance chain",
        "description": "The Ed25519 receipt chain: cryptographic proof of when the article was fetched, scraped, and analyzed.",
        "tags": [
          "Articles"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvenanceChain"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/articles/{id}/content": {
      "get": {
        "summary": "Article hashed content",
        "description": "The exact bytes (analysis JSON / extracted text) behind the content hash, for in-browser re-hash verification.",
        "tags": [
          "Articles"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The hashed content payload."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/signals": {
      "get": {
        "summary": "Momentum signals",
        "description": "Market-momentum signals from news. sort=\"extreme\" ranks by magnitude x strength (biggest movers) instead of newest.",
        "tags": [
          "Signals"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"TSLA\"."
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "UP",
                "DOWN"
              ]
            }
          },
          {
            "name": "asset_class",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"equity\", \"crypto\"."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "24h"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 24h."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "description": "Rows to return. Default 50, cap 200 (server-clamped)."
          },
          {
            "name": "min_strength",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Minimum strength, 0-100."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "extreme"
              ]
            },
            "description": "Top movers first."
          }
        ],
        "responses": {
          "200": {
            "description": "Signal list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "signals": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Signal"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/topics": {
      "get": {
        "summary": "Trending topics",
        "description": "Topics ranked by article volume over a window.",
        "tags": [
          "Signals"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "24h"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 24h."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows to return. Default 30, cap 100 (server-clamped)."
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked topics."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/suggestions": {
      "get": {
        "summary": "Discover suggestions",
        "description": "Ranked discovery suggestions powering the Discover board.",
        "tags": [
          "Signals"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/open-signals": {
      "get": {
        "summary": "Open intel signals",
        "description": "Public-data signals: prediction markets, legislation, economic releases, seismic feeds.",
        "tags": [
          "Intel"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"fred\", \"polymarket\"."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "7d"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 7d."
          }
        ],
        "responses": {
          "200": {
            "description": "Open-signal rows."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/open-signals/sources": {
      "get": {
        "summary": "Open-signal sources",
        "description": "The list of open-data sources currently ingested.",
        "tags": [
          "Intel"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/open-signals/series": {
      "get": {
        "summary": "Open-signal series",
        "description": "A single time series for one open-data entity (e.g. a FRED series, a Polymarket market).",
        "tags": [
          "Intel"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"fred\"."
          },
          {
            "name": "entity_key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"CPIAUCSL\"."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "1y"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 1y."
          }
        ],
        "responses": {
          "200": {
            "description": "The value series."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/open-signals/series-all": {
      "get": {
        "summary": "All open-signal series",
        "description": "Every tracked series for a source in one call.",
        "tags": [
          "Intel"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/entities": {
      "get": {
        "summary": "Entity search",
        "description": "Named entities (people, orgs, tickers) extracted from the record, plus the trending set.",
        "tags": [
          "Graph"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"Jensen Huang\"."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"person\", \"org\"."
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "description": "Rows to return. Default 50, cap 200 (server-clamped)."
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Content-kind filter (comma-separated): news | blog | release_notes | spec | forum_social. Omit for all kinds; an invalid value is a 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Entities + trending",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entities": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Entity"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "summary": "Event calendar",
        "description": "Events extracted from news: deadlines, launches, earnings, hearings.",
        "tags": [
          "Graph"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"deadline\"."
          },
          {
            "name": "upcoming",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Only future events."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "7d"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 7d."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "description": "Rows to return. Default 50, cap 200 (server-clamped)."
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Content-kind filter (comma-separated): news | blog | release_notes | spec | forum_social. Omit for all kinds; an invalid value is a 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Event list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/facts": {
      "get": {
        "summary": "Fact search",
        "description": "Discrete facts extracted from articles, filterable by subject.",
        "tags": [
          "Graph"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "subject",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. \"Federal Reserve\"."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "7d"
            },
            "description": "Time window, e.g. \"1h\", \"24h\", \"7d\", \"30d\". Default 7d."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "description": "Rows to return. Default 50, cap 200 (server-clamped)."
          }
        ],
        "responses": {
          "200": {
            "description": "Fact list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "facts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Fact"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/claims": {
      "get": {
        "summary": "Corroborated claim browse",
        "description": "Statements carried word-for-word by 2+ publishers, with counts, first/last seen and contested flags. The DEFAULT browse holds back generic process boilerplate and reports how many rows it held back in generic_excluded (additive field, 2026-08-05); pass generic=1 for the raw uncurated tier. Not independent origins: syndication is not collapsed.",
        "tags": [
          "Graph"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter claims by text (disables curation)."
          },
          {
            "name": "view",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "alpha",
                "exact",
                "near",
                "all"
              ]
            },
            "description": "Claim tier; default alpha (de-duplicated)."
          },
          {
            "name": "generic",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ]
            },
            "description": "1 = include generic boilerplate claims the default browse holds back."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "description": "Rows to return. Default 50, cap 200 (server-clamped)."
          }
        ],
        "responses": {
          "200": {
            "description": "Claim list plus generic_excluded (how many boilerplate rows the default curation held back)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/digests": {
      "get": {
        "summary": "Digests",
        "description": "Recent category digests.",
        "tags": [
          "Digests"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            },
            "description": "Rows to return. Default 10, cap 50 (server-clamped)."
          }
        ]
      }
    },
    "/v1/digests/reader": {
      "get": {
        "summary": "Reader digests",
        "description": "Latest brief per kind in section order (regions, languages, topics, signals).",
        "tags": [
          "Digests"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/digests/movers": {
      "get": {
        "summary": "Market movers brief",
        "description": "The signed movers brief: the day's biggest ranked market moves.",
        "tags": [
          "Digests"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/digests/house": {
      "get": {
        "summary": "House digests",
        "description": "The flagship controversy / quality / momentum briefs.",
        "tags": [
          "Digests"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/digests/intel": {
      "get": {
        "summary": "Intel digests",
        "description": "Per-source intel briefs, alias-resolved across the 24h and 7d windows.",
        "tags": [
          "Digests"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/digests/kind/{kind}": {
      "get": {
        "summary": "Digest by kind",
        "description": "One brief kind, optionally windowed.",
        "tags": [
          "Digests"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "24h",
                "7d"
              ]
            }
          }
        ]
      }
    },
    "/v1/snapshots": {
      "get": {
        "summary": "Captured days",
        "description": "Every frozen, signed day in the TruthFoundry Archive.",
        "tags": [
          "Archive"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/snapshots/{date}": {
      "get": {
        "summary": "One frozen day",
        "description": "The full signed record for one day: manifest + briefs, source-hydrated.",
        "tags": [
          "Archive"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "date",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "YYYY-MM-DD (UTC)."
          }
        ]
      }
    },
    "/v1/sources": {
      "get": {
        "summary": "Publishers",
        "description": "Every publisher in the index.",
        "tags": [
          "Archive"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/sources/{id}": {
      "get": {
        "summary": "Publisher detail",
        "description": "One publisher's recent coverage.",
        "tags": [
          "Archive"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/query/templates": {
      "get": {
        "summary": "Query templates",
        "description": "The hardened templates an agent can run or schedule, with typed parameter surfaces.",
        "tags": [
          "Smart Query"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/query/steps": {
      "get": {
        "summary": "Advanced step catalog",
        "description": "Producers and transformers for user-composed Advanced Smart Query pipelines.",
        "tags": [
          "Smart Query"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/query": {
      "post": {
        "summary": "Run a query template",
        "description": "Run a hardened intelligence pipeline and return a cited, ranked result now. Requires a PAID key (the demo/free key is rejected).",
        "tags": [
          "Smart Query"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "template"
                ],
                "properties": {
                  "template": {
                    "type": "string",
                    "example": "controversy-radar"
                  },
                  "params": {
                    "type": "object",
                    "description": "Only the knobs the template declares."
                  },
                  "output": {
                    "type": "string",
                    "enum": [
                      "json",
                      "digest"
                    ],
                    "default": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cited, ranked result."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/query/advanced": {
      "post": {
        "summary": "Run an advanced pipeline",
        "description": "Run a validated, user-composed {name?, steps} pipeline (16-step cap) over the record. Requires a PAID key.",
        "tags": [
          "Smart Query"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "steps"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "maxItems": 16
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The pipeline result."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/query/generate": {
      "get": {
        "summary": "Generate a pipeline",
        "description": "Draft an Advanced Smart Query pipeline from a natural-language goal. Requires a paid key.",
        "tags": [
          "Smart Query"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "name": "goal",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "What you want the pipeline to do."
          }
        ]
      }
    },
    "/v1/usage": {
      "get": {
        "summary": "Your usage",
        "description": "Today's request count and remaining daily budget for your key.",
        "tags": [
          "Account"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/home": {
      "get": {
        "summary": "Homepage payload",
        "description": "The homepage payload plus the fresh breaking hero. Powers the web home.",
        "tags": [
          "Account"
        ],
        "x-metering": "metered",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Newsboy-Key",
        "description": "TruthFoundry API key (nwb_... or drm3_...). Also accepted as `Authorization: Bearer <key>`. Get one at /pricing."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, invalid, or revoked API key. Send the key on every /v1/* request. The full record is free to read on the web; a key (free demo or paid) opens the API. See /pricing.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AuthError"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limited. Each key has a per-minute burst budget plus a daily volume cap (both scale with tier: free 60/min + 100/day up to scale 600/min + 100k/day). Daily caps reset at 00:00 UTC. The Retry-After header (seconds) says when to try again; X-Newsboy-Daily-Limit / X-Newsboy-Daily-Used report the daily budget.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AuthError"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "x402 agent micropayment offered. A KEYLESS request to a metered endpoint (when x402 is enabled) gets this instead of a 401: an x402 'exact' scheme envelope (accepts + offers + hint). Retry with an X-PAYMENT header carrying a signed EIP-3009 transferWithAuthorization for USDC on Base to pay per call, or read the full record free on the web, or get a key at /pricing. A verified payment is acknowledged in the X-PAYMENT-RESPONSE header.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "x402Version": {
                  "type": "integer",
                  "example": 1
                },
                "accepts": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "scheme": {
                        "type": "string",
                        "example": "exact"
                      },
                      "network": {
                        "type": "string",
                        "example": "base"
                      },
                      "maxAmountRequired": {
                        "type": "string",
                        "example": "10000",
                        "description": "Price in atomic USDC units (6 decimals)."
                      },
                      "payTo": {
                        "type": "string",
                        "description": "The operator's receive address."
                      },
                      "asset": {
                        "type": "string",
                        "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
                      },
                      "maxTimeoutSeconds": {
                        "type": "integer",
                        "example": 60
                      }
                    }
                  }
                },
                "offers": {
                  "type": "object",
                  "description": "The access-door menu: free web, x402 pay-per-call, and standing API tiers."
                },
                "hint": {
                  "type": "string",
                  "description": "Plain-language pointer to the payment and access options."
                }
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "Unexpected server error. Safe to retry with backoff; check /health for sync and service status.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Article": {
        "type": "object",
        "description": "An article with its AI-extracted structured fields. Paid tiers get the full field set; free/demo keys get the public subset.",
        "properties": {
          "id": {
            "type": "string",
            "example": "a1b2c3"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "ai_title": {
            "type": "string",
            "description": "Model-normalized headline (reader surfaces gate on this being non-empty)."
          },
          "source_name": {
            "type": "string"
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          },
          "language": {
            "type": "string",
            "example": "en"
          },
          "kind": {
            "type": "string",
            "enum": [
              "news",
              "blog",
              "release_notes",
              "spec",
              "forum_social"
            ]
          },
          "summary": {
            "type": "string"
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Entity"
            }
          },
          "signals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Signal"
            }
          },
          "_receipt": {
            "type": "string",
            "description": "Provenance receipt id; resolve at /receipts/{id}.",
            "nullable": true
          }
        }
      },
      "ArticleList": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "example": 42
          },
          "articles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          }
        }
      },
      "Entity": {
        "type": "object",
        "properties": {
          "canonical_name": {
            "type": "string",
            "example": "Nvidia"
          },
          "type": {
            "type": "string",
            "example": "org"
          },
          "ticker": {
            "type": "string",
            "nullable": true,
            "example": "NVDA"
          },
          "mentions": {
            "type": "integer",
            "example": 128
          }
        }
      },
      "Signal": {
        "type": "object",
        "description": "A market-momentum signal extracted from an article.",
        "properties": {
          "ticker": {
            "type": "string",
            "example": "TSLA"
          },
          "direction": {
            "type": "string",
            "enum": [
              "UP",
              "DOWN",
              "FLAT"
            ]
          },
          "asset_class": {
            "type": "string",
            "example": "equity"
          },
          "magnitude": {
            "type": "number",
            "description": "Move size on a 0-16 scale."
          },
          "strength": {
            "type": "number",
            "description": "Signal confidence, 0-100."
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "article_id": {
            "type": "string"
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "example": "earnings"
          },
          "title": {
            "type": "string"
          },
          "event_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "subject": {
            "type": "string"
          },
          "article_id": {
            "type": "string"
          }
        }
      },
      "Fact": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "example": "Federal Reserve"
          },
          "type": {
            "type": "string"
          },
          "statement": {
            "type": "string"
          },
          "article_id": {
            "type": "string"
          }
        }
      },
      "Digest": {
        "type": "object",
        "description": "A signed, cited brief composed over a slice of the record.",
        "properties": {
          "kind": {
            "type": "string",
            "example": "controversy"
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string",
            "description": "Markdown, with [n] footnote citations into items[]."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Cited sources, indexed by footnote."
          },
          "content_sig": {
            "type": "string",
            "description": "Ed25519 signature over the brief content."
          },
          "built_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ProvenanceChain": {
        "type": "object",
        "description": "The Ed25519 receipt chain for an article: fetch, scrape, and analyze legs, each signed.",
        "properties": {
          "article_id": {
            "type": "string"
          },
          "receipts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "example": "content.analyze"
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time"
                },
                "inputHash": {
                  "type": "string"
                },
                "outputHash": {
                  "type": "string"
                },
                "publicKey": {
                  "type": "string"
                },
                "signature": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Snapshot": {
        "type": "object",
        "description": "One frozen, signed day of the TruthFoundry Archive.",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "example": "2026-07-04"
          },
          "manifest_sha256": {
            "type": "string"
          },
          "briefs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Digest"
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "tier": {
            "type": "string",
            "example": "pro"
          },
          "daily_limit": {
            "type": "integer",
            "example": 10000
          },
          "used_today": {
            "type": "integer",
            "example": 137
          },
          "remaining": {
            "type": "integer",
            "example": 9863
          },
          "resets_at": {
            "type": "string",
            "format": "date-time",
            "description": "00:00 UTC."
          }
        }
      },
      "Health": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          },
          "version": {
            "type": "string"
          },
          "articles": {
            "type": "integer",
            "description": "Articles in the record, a live estimate. Publisher and language totals ride beside it."
          }
        }
      },
      "AuthError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "KEY_NOT_FOUND"
              },
              "message": {
                "type": "string",
                "example": "Invalid API key. Get a free key at /pricing."
              }
            }
          }
        }
      }
    }
  }
}