{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://throughline.markets/schema/throughline-v3.json",
  "title": "Throughline public feed (ThroughlinePublicationV3)",
  "description": "Shapes returned by the Throughline feed routes. Facts version 2026-11-13.1, derived from service source d8d2f2c.",
  "x-facts-version": "2026-11-13.1",
  "$ref": "#/$defs/Envelope",
  "$defs": {
    "Text": {
      "type": "string",
      "minLength": 1,
      "description": "Non-blank text without control characters."
    },
    "Clock": {
      "type": "string",
      "pattern": "^\\d{4}-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d(\\.\\d{1,6})?(Z|[+-]\\d\\d:\\d\\d)$",
      "description": "RFC 3339 timestamp with seconds, optional fraction and an explicit Z or numeric offset."
    },
    "Url": {
      "type": "string",
      "pattern": "^https?://",
      "description": "Public http(s) URL. Metadata only; the API never fetches it."
    },
    "StreamId": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_-]{1,64}$"
    },
    "RecordId": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "sha256 of the canonical JSON array [\"ThroughlineLinkV1\", report_id, venue, condition_id]."
    },
    "Envelope": {
      "description": "One change to one match. Identity is the (stream_id, record_id) pair.",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "schema",
            "stream_id",
            "sequence",
            "operation",
            "record_id",
            "record"
          ],
          "properties": {
            "schema": {
              "const": "ThroughlinePublicationV3"
            },
            "stream_id": {
              "$ref": "#/$defs/StreamId"
            },
            "sequence": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9223372036854775807
            },
            "operation": {
              "const": "upsert"
            },
            "record_id": {
              "$ref": "#/$defs/RecordId"
            },
            "record": {
              "$ref": "#/$defs/Record"
            }
          },
          "description": "Complete replacement of the match."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "schema",
            "stream_id",
            "sequence",
            "operation",
            "record_id",
            "record"
          ],
          "properties": {
            "schema": {
              "const": "ThroughlinePublicationV3"
            },
            "stream_id": {
              "$ref": "#/$defs/StreamId"
            },
            "sequence": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9223372036854775807
            },
            "operation": {
              "const": "withdraw"
            },
            "record_id": {
              "$ref": "#/$defs/RecordId"
            },
            "record": {
              "type": "null"
            }
          },
          "description": "The match is withdrawn; record is null."
        }
      ]
    },
    "Record": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "report_id",
        "source_revision_id",
        "source_revision_kind",
        "publisher",
        "title",
        "url",
        "language",
        "published_at",
        "received_at",
        "source_clock_status",
        "captured_content",
        "publisher_completeness",
        "market",
        "relevance",
        "analysis",
        "evidence"
      ],
      "properties": {
        "report_id": {
          "$ref": "#/$defs/Text"
        },
        "source_revision_id": {
          "$ref": "#/$defs/Text"
        },
        "source_revision_kind": {
          "enum": [
            "captured_feed_revision"
          ]
        },
        "publisher": {
          "$ref": "#/$defs/Text"
        },
        "title": {
          "$ref": "#/$defs/Text"
        },
        "url": {
          "$ref": "#/$defs/Url"
        },
        "language": {
          "$ref": "#/$defs/Text"
        },
        "published_at": {
          "anyOf": [
            {
              "$ref": "#/$defs/Clock"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the source says it published. Null exactly when source_clock_status is missing."
        },
        "received_at": {
          "$ref": "#/$defs/Clock",
          "description": "When the article revision was received."
        },
        "source_clock_status": {
          "enum": [
            "reported",
            "unreliable",
            "missing"
          ]
        },
        "captured_content": {
          "enum": [
            "headline_only",
            "summary",
            "body"
          ],
          "description": "What text the assessment had: headline only, a summary, or the article body."
        },
        "publisher_completeness": {
          "enum": [
            "unknown"
          ],
          "description": "Whether the publisher's output was captured completely. Always unknown."
        },
        "market": {
          "$ref": "#/$defs/Market"
        },
        "relevance": {
          "$ref": "#/$defs/Relevance"
        },
        "analysis": {
          "anyOf": [
            {
              "$ref": "#/$defs/Analysis"
            },
            {
              "type": "null"
            }
          ],
          "description": "Null until, and unless, a closer reading is published."
        },
        "evidence": {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "$ref": "#/$defs/Evidence"
          },
          "description": "Exactly one entry: the record's own article revision."
        }
      },
      "description": "One article matched to one contract.",
      "allOf": [
        {
          "if": {
            "properties": {
              "source_clock_status": {
                "const": "missing"
              }
            }
          },
          "then": {
            "properties": {
              "published_at": {
                "type": "null"
              }
            }
          },
          "else": {
            "properties": {
              "published_at": {
                "$ref": "#/$defs/Clock"
              }
            }
          }
        }
      ]
    },
    "Market": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "venue",
        "condition_id",
        "title",
        "url",
        "rules_sha256",
        "deadline_at"
      ],
      "properties": {
        "venue": {
          "$ref": "#/$defs/Text"
        },
        "condition_id": {
          "$ref": "#/$defs/Text",
          "description": "The venue's exact condition ID. Not a slug, event ID or token ID."
        },
        "title": {
          "$ref": "#/$defs/Text"
        },
        "url": {
          "anyOf": [
            {
              "$ref": "#/$defs/Url"
            },
            {
              "type": "null"
            }
          ]
        },
        "rules_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "sha256 of the rule text the match was made against."
        },
        "deadline_at": {
          "anyOf": [
            {
              "$ref": "#/$defs/Clock"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "description": "The contract the article was matched to."
    },
    "Relevance": {
      "description": "The first-pass (preliminary) assessment. Always present.",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "stage",
            "assessed_at",
            "verdict",
            "novelty",
            "why_relevant",
            "explanation_kind"
          ],
          "properties": {
            "stage": {
              "const": "scout"
            },
            "assessed_at": {
              "$ref": "#/$defs/Clock"
            },
            "verdict": {
              "enum": [
                "relevant",
                "uncertain"
              ]
            },
            "novelty": {
              "enum": [
                "new",
                "update",
                "repeat",
                "uncertain"
              ]
            },
            "why_relevant": {
              "type": "null"
            },
            "explanation_kind": {
              "const": "unavailable"
            }
          },
          "description": "No publishable explanation was produced; why_relevant is null."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "stage",
            "assessed_at",
            "verdict",
            "novelty",
            "why_relevant",
            "explanation_kind"
          ],
          "properties": {
            "stage": {
              "const": "scout"
            },
            "assessed_at": {
              "$ref": "#/$defs/Clock"
            },
            "verdict": {
              "enum": [
                "relevant",
                "uncertain"
              ]
            },
            "novelty": {
              "enum": [
                "new",
                "update",
                "repeat",
                "uncertain"
              ]
            },
            "why_relevant": {
              "$ref": "#/$defs/Text"
            },
            "explanation_kind": {
              "const": "public_explanation"
            }
          },
          "description": "A public explanation is present."
        }
      ]
    },
    "Analysis": {
      "description": "The closer reading (assessed). Price-blind.",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "stage",
            "assessed_at",
            "report_status",
            "impact",
            "why_relevant",
            "explanation_kind"
          ],
          "properties": {
            "stage": {
              "const": "analyst"
            },
            "assessed_at": {
              "$ref": "#/$defs/Clock"
            },
            "report_status": {
              "enum": [
                null,
                "reported",
                "unverified",
                "contradicted",
                "repeat"
              ]
            },
            "impact": {
              "type": "integer",
              "minimum": 0,
              "maximum": 4,
              "description": "A model's reading of how much the story bears on the contract. Not a probability and not calibrated confidence."
            },
            "why_relevant": {
              "type": "null"
            },
            "explanation_kind": {
              "const": "unavailable"
            }
          },
          "description": "No publishable explanation was produced; why_relevant is null."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "stage",
            "assessed_at",
            "report_status",
            "impact",
            "why_relevant",
            "explanation_kind"
          ],
          "properties": {
            "stage": {
              "const": "analyst"
            },
            "assessed_at": {
              "$ref": "#/$defs/Clock"
            },
            "report_status": {
              "enum": [
                null,
                "reported",
                "unverified",
                "contradicted",
                "repeat"
              ]
            },
            "impact": {
              "type": "integer",
              "minimum": 0,
              "maximum": 4,
              "description": "A model's reading of how much the story bears on the contract. Not a probability and not calibrated confidence."
            },
            "why_relevant": {
              "$ref": "#/$defs/Text"
            },
            "explanation_kind": {
              "const": "public_explanation"
            }
          },
          "description": "A public explanation is present."
        }
      ]
    },
    "Evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "report_id",
        "source_revision_id",
        "url"
      ],
      "properties": {
        "report_id": {
          "$ref": "#/$defs/Text"
        },
        "source_revision_id": {
          "$ref": "#/$defs/Text"
        },
        "url": {
          "$ref": "#/$defs/Url"
        }
      }
    },
    "Change": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "cursor",
        "envelope"
      ],
      "properties": {
        "cursor": {
          "type": "integer",
          "minimum": 1
        },
        "envelope": {
          "$ref": "#/$defs/Envelope"
        }
      },
      "description": "One feed item, and the response of GET /v1/news/{record_id}."
    },
    "NewsPage": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "items",
        "next_cursor",
        "has_more"
      ],
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Change"
          }
        },
        "next_cursor": {
          "type": "integer",
          "minimum": 0
        },
        "has_more": {
          "type": "boolean"
        }
      },
      "description": "A page of changes, oldest first. A market-filtered page may be empty while has_more is true."
    },
    "Coverage": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "declared_scope",
        "publisher_availability",
        "screened_coverage",
        "screened_coverage_status",
        "meaning",
        "source_policy"
      ],
      "properties": {
        "schema": {
          "const": "ThroughlineCoverageV1"
        },
        "declared_scope": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/Text"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "publisher_availability": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "publisher",
                  "status",
                  "as_of"
                ],
                "properties": {
                  "publisher": {
                    "$ref": "#/$defs/Text"
                  },
                  "status": {
                    "enum": [
                      "available",
                      "delayed",
                      "unavailable",
                      "unknown"
                    ]
                  },
                  "as_of": {
                    "$ref": "#/$defs/Clock"
                  }
                }
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "screened_coverage": {
          "type": "null"
        },
        "screened_coverage_status": {
          "const": "unknown"
        },
        "meaning": {
          "type": "string"
        },
        "source_policy": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "start",
            "historical_backfill",
            "match_evidence",
            "unsupported_evidence",
            "source_loss_before_public_commit",
            "dynamic_source_status",
            "research_archive"
          ],
          "properties": {
            "start": {
              "const": "activation"
            },
            "historical_backfill": {
              "const": false
            },
            "match_evidence": {
              "const": "primary_article_alone"
            },
            "unsupported_evidence": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "source_loss_before_public_commit": {
              "const": "possible"
            },
            "dynamic_source_status": {
              "const": "unknown"
            },
            "research_archive": {
              "const": false
            }
          }
        }
      },
      "description": "Supplied coverage facts. Screening status is unknown and is reported as unknown."
    },
    "Usage": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "window_seconds",
        "reset_at",
        "requests",
        "bytes",
        "request_limit",
        "byte_limit",
        "requests_remaining",
        "bytes_remaining"
      ],
      "properties": {
        "window_seconds": {
          "type": "integer",
          "minimum": 0
        },
        "reset_at": {
          "type": "integer",
          "minimum": 0
        },
        "requests": {
          "type": "integer",
          "minimum": 0
        },
        "bytes": {
          "type": "integer",
          "minimum": 0
        },
        "request_limit": {
          "type": "integer",
          "minimum": 0
        },
        "byte_limit": {
          "type": "integer",
          "minimum": 0
        },
        "requests_remaining": {
          "type": "integer",
          "minimum": 0
        },
        "bytes_remaining": {
          "type": "integer",
          "minimum": 0
        }
      },
      "description": "Account usage in the current window. reset_at is Unix seconds."
    },
    "Error": {
      "type": "object",
      "required": [
        "error",
        "message",
        "docs_url",
        "request_id"
      ],
      "properties": {
        "error": {
          "enum": [
            "unauthorized",
            "missing_or_malformed_key",
            "invalid_key",
            "account_unavailable",
            "origin_forbidden",
            "verified_identity_required",
            "scope_forbidden",
            "not_found",
            "method_not_allowed",
            "ambiguous_record",
            "active_key_limit",
            "connection_capacity",
            "consent_conflict",
            "key_creation_conflict",
            "credential_conflict",
            "trial_unavailable",
            "builder_already_active",
            "invalid_request",
            "invalid_path",
            "invalid_query",
            "invalid_pagination",
            "invalid_limit",
            "invalid_cursor",
            "invalid_stream",
            "conflicting_market",
            "invalid_market_id",
            "invalid_content_length",
            "unexpected_body",
            "invalid_body",
            "invalid_key_name",
            "invalid_scopes",
            "invalid_credential_hash",
            "authorization_pending",
            "access_denied",
            "expired_token",
            "content_length_required",
            "request_too_large",
            "request_target_too_large",
            "json_required",
            "account_quota_exceeded",
            "account_data_limit",
            "coverage_quota_exceeded",
            "usage_quota_exceeded",
            "management_quota_exceeded",
            "agent_quota_exceeded",
            "approval_limited",
            "pairing_capacity",
            "billing_quota_exceeded",
            "burst_limited",
            "burst_capacity",
            "server_capacity",
            "billing_subscription_exists",
            "billing_checkout_needs_recovery",
            "billing_checkout_needs_refresh",
            "billing_customer_unavailable",
            "billing_attempt_unknown",
            "billing_provider_unavailable",
            "billing_payment_conflict",
            "service_busy",
            "service_unavailable",
            "response_too_large",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "The code in words, for people. Not stable; branch on error."
        },
        "docs_url": {
          "const": "https://throughline.markets/api#errors"
        },
        "request_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{32}$",
          "description": "Also sent as the X-Request-ID header."
        },
        "usage": {
          "$ref": "#/$defs/Usage"
        },
        "upgrade_url": {
          "type": "string",
          "description": "Only on account_quota_exceeded and account_data_limit: where the person can change plan."
        },
        "reset_at": {
          "type": "integer",
          "minimum": 0,
          "description": "Only on account_quota_exceeded and account_data_limit: Unix seconds when the allowance resets."
        },
        "status": {
          "const": "pending",
          "description": "Only on authorization_pending."
        }
      },
      "description": "Every JSON error on the customer-callable feed, account, billing and pairing routes. error is the stable code. Further fields may be added; ignore fields you do not know. Three further codes (invalid_webhook, invalid_stripe_event, billing_event_conflict; each 400) are returned only to provider webhook deliveries and are deliberately not in this enum."
    },
    "UsageReport": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "plan",
        "usage"
      ],
      "properties": {
        "plan": {
          "type": "string",
          "description": "free, evaluation (the seven-day trial) or builder; older accounts may show another label."
        },
        "usage": {
          "$ref": "#/$defs/Usage"
        }
      },
      "description": "GET /v1/usage: the account's plan and usage in the current window."
    }
  }
}
