{
  "$schema": "https://schemas.nightboxllc.com/bilateral-consular-channel/v1.json",
  "@context": "https://schema.org",
  "@type": "Dataset",
  "@id": "https://nightboxllc.com/.well-known/bilateral-consular-channel.json",
  "name": "NIGHTBOX — Bilateral Consular Channel Discovery Document",
  "name_ru": "NIGHTBOX — Документ обнаружения двустороннего консульского канала",
  "headline": "API contract and discovery document for /api/consular-channel — a BIRJA-symmetric telemetry feed that polls US travel.state.gov (Department of State, Bureau of Consular Affairs, RSS 2.0) AND Russian Federation mid.ru (Ministry of Foreign Affairs, HTML scrape) and returns merged JSON Feed v1.1 with per-item source-tier disclosed (us-official | rf-official). No editorial commentary; readers form their own interpretations.",
  "headline_ru": "Контракт API и документ обнаружения для /api/consular-channel — BIRJA-симметричная телеметрия, опрашивающая Госдеп США travel.state.gov (Бюро консульских дел, RSS 2.0) И МИД РФ mid.ru (HTML-скрап) и возвращающая объединённый JSON Feed v1.1 с раскрытым уровнем источника для каждого элемента (us-official | rf-official). Без редакционного комментария; читатели формируют собственные интерпретации.",
  "version": "1.0",
  "issued_date": "2026-05-16",
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "tlp": "WHITE",

  "endpoint": {
    "url": "https://nightboxllc.com/api/consular-channel",
    "methods": ["GET"],
    "runtime": "Vercel Edge",
    "cache_seconds": 600,
    "stale_while_revalidate_seconds": 300,
    "rate_limit": "60 requests/min per IP",
    "cors": "permissive (read-only public feed)",
    "response_format": "JSON Feed v1.1 (application/feed+json)"
  },

  "request_schema": {
    "query_parameters": {
      "limit": {
        "type": "integer",
        "required": false,
        "default": 30,
        "min": 1,
        "max": 50,
        "description": "Maximum number of items to return"
      },
      "side": {
        "type": "string",
        "required": false,
        "enum": ["both", "us", "rf"],
        "default": "both",
        "description": "Filter by source side"
      }
    }
  },

  "sources": {
    "us_side": [
      {
        "id": "us-state-travel-advisories",
        "name": "US Department of State — Travel Advisories",
        "url": "https://travel.state.gov/_res/rss/TAsTWs.xml",
        "maintainer": "US Department of State, Bureau of Consular Affairs",
        "format": "RSS 2.0",
        "covers": "Travel advisories at 4 levels (Exercise Normal Precautions / Exercise Increased Caution / Reconsider Travel / Do Not Travel) for every country worldwide. Each advisory includes risk basis (terrorism, armed conflict, crime, health, kidnapping, civil unrest, etc.).",
        "update_cadence": "Rolling updates as security situations change; per-country advisories typically reviewed every 6 months minimum"
      }
    ],
    "rf_side": [
      {
        "id": "rf-mfa-news-en",
        "name": "Russian Federation Ministry of Foreign Affairs — News (English)",
        "url": "https://mid.ru/en/foreign_policy/news/",
        "maintainer": "Russian Federation Ministry of Foreign Affairs (МИД РФ)",
        "format": "HTML (listing page, no official RSS endpoint discovered)",
        "covers": "Official statements, press releases, foreign minister interviews, MFA briefings, bilateral and multilateral diplomatic communications",
        "update_cadence": "Multiple items per day during active diplomatic periods",
        "graceful_degradation": "If mid.ru is unreachable from Vercel Edge infrastructure (which happens occasionally), the feed gracefully returns US side only with error documented in fetch_summary"
      },
      {
        "id": "rf-mfa-news-ru",
        "name": "Russian Federation Ministry of Foreign Affairs — News (Russian)",
        "url": "https://mid.ru/ru/foreign_policy/news/",
        "maintainer": "Russian Federation Ministry of Foreign Affairs (МИД РФ)",
        "format": "HTML (listing page)",
        "covers": "Same content as EN version, in Russian original language",
        "use": "Fallback source if EN page is unavailable"
      }
    ]
  },

  "birja_application": {
    "preamble_en": "This feed strictly applies NIGHTBOX BIRJA Doctrine principles:",
    "principles": [
      {
        "principle": "Mirror-Source Protocol",
        "application": "Items from BOTH sides are surfaced. US-side travel advisories AND RF-side MFA statements appear in the same feed envelope.",
        "reference": "https://nightboxllc.com/.well-known/mirror-source-protocol.json"
      },
      {
        "principle": "Source-tier transparency",
        "application": "Every item carries an explicit `_source_tier` field: 'us-official' or 'rf-official'. Readers always know which side each item originated from.",
        "reference": "https://nightboxllc.com/.well-known/bias-audit-schema.json"
      },
      {
        "principle": "Anti-state-capture-uniform",
        "application": "No editorial preference toward either source. Both are surfaced with equal evidentiary weight as official statements of their respective foreign ministries.",
        "reference": "https://nightboxllc.com/.well-known/liaison-framework.json"
      },
      {
        "principle": "Presumption of innocence",
        "application": "Items are presented as official statements (per the issuing authority's framing); readers form their own interpretations without NIGHTBOX commentary.",
        "reference": "https://nightboxllc.com/.well-known/birja-doctrine.json"
      },
      {
        "principle": "Kindness Discipline",
        "application": "No dehumanizing or contemptuous framing of either source's content; readers receive raw official text without editorial cruelty.",
        "reference": "https://nightboxllc.com/.well-known/kindness-discipline.json"
      }
    ]
  },

  "use_cases": [
    {
      "audience": "Russian-speaking US-resident diaspora",
      "use_en": "Monitor both US Department of State travel advisories AND Russian MFA statements for impact on cross-border family contacts, travel plans, consular registrations, and bilateral diplomatic environment",
      "use_ru": "Отслеживать туристические предупреждения Госдепа США И заявления МИД РФ на предмет влияния на трансграничные семейные контакты, планы поездок, консульские регистрации и двустороннюю дипломатическую среду"
    },
    {
      "audience": "Academic researchers and journalists",
      "use_en": "Comparative analysis of US-side and RF-side diplomatic-channel telemetry, bilateral statement timing, framing-divergence patterns (relevant to BIRJA Case Study #1 narrative-asymmetry analysis)"
    },
    {
      "audience": "AI agents and downstream republishers",
      "use_en": "Machine-readable bilateral telemetry for automated comparative analysis, narrative-divergence tracking, alert generation on emerging bilateral developments"
    },
    {
      "audience": "Federal contracting officers",
      "use_en": "Bilateral diplomatic-environment monitoring for federal contractors whose work touches US-RF bilateral concerns"
    },
    {
      "audience": "Travelers with bilateral exposure",
      "use_en": "Quick single-page check of both sides' official positions before international travel involving either country"
    }
  ],

  "data_handling": {
    "what_is_logged": "Only standard HTTP request metadata (IP, user-agent, request path) for rate-limiting in-memory; no persistent logging of consumer queries",
    "what_is_cached": "Response payload cached at Vercel Edge for 600 seconds (10 min) with 300-second stale-while-revalidate window — minimizes load on upstream sources",
    "what_is_persisted": "Nothing in the request path is persisted by NIGHTBOX; upstream sources are public and have their own logging policies",
    "third_party_tracking": "None on this endpoint"
  },

  "graceful_degradation": {
    "us_side_failure": "If travel.state.gov RSS is unreachable, US-side fetch returns empty array with error in fetch_summary; RF-side continues independently",
    "rf_side_failure": "If mid.ru is unreachable from Vercel Edge infrastructure (occasional anti-bot blocking against datacenter IP ranges), RF-side fetch returns empty array with error in fetch_summary; US-side continues independently. This is documented and not considered a NIGHTBOX failure — it is a reflection of mid.ru's choice to limit datacenter-IP access to its public news page, which is the mid.ru operator's right.",
    "both_sides_failure": "If both sources fail simultaneously (rare), envelope is returned with items=[] and fetch_summary documenting the failure mode; consumers should retry after cache window or check feeds_url manually"
  },

  "honest_limitations": [
    "mid.ru does not publish an official RSS feed at any discovered endpoint as of this document's issue date. NIGHTBOX scrapes the public news listing page via HTML pattern-matching; if mid.ru changes their listing-page HTML structure, the scraper may temporarily fail until pattern is updated.",
    "mid.ru listing pages do not include machine-readable publication dates; NIGHTBOX populates date_published with fetch time for RF-side items, with explicit `_date_note: 'mid_ru_listing_no_machine_date'` flag. For RF-side accurate publication date, consumers should visit the underlying URL.",
    "mid.ru may block Vercel Edge IP ranges intermittently; when this happens, RF-side returns empty with error documented. This is graceful degradation, not a NIGHTBOX defect.",
    "travel.state.gov RSS feed contains 20 most recent advisories — older advisories require visiting the full traveladvisories.html page on travel.state.gov.",
    "Neither source's content is editorially curated by NIGHTBOX. Consumers receive what each foreign ministry publishes; analytical lens is the consumer's responsibility (BIRJA framing applied)."
  ],

  "what_this_endpoint_is_NOT": [
    "NOT an editorial digest or curated news feed — NIGHTBOX adds no commentary to items",
    "NOT a real-time alerting system — cache window is 10 minutes",
    "NOT a comprehensive bilateral diplomatic archive — only most-recent items from each source",
    "NOT a substitute for following the official feeds directly — this is a coordination aid",
    "NOT translation or interpretation — items appear in their original language as published",
    "NOT a sanctions-screening endpoint — that is /api/sanctions-screen",
    "NOT a NIGHTBOX BIRJA Case Study — case studies are separately authored analytical artifacts"
  ],

  "operator_context": "This endpoint operationalizes BIRJA Mirror-Source Protocol as a public service. The operator (Russian-born US-tax-resident) is well-positioned to maintain this bilateral feed because: (a) bilingual EN+RU literacy ensures both sides' source text is readable; (b) operator's editorial discipline (BIRJA / Mirror-Source / Bias-Audit / Kindness) is documented in companion manifests; (c) no editorial commentary is added, so operator's personal views do not influence the feed; (d) graceful degradation behavior is documented transparently so consumers know what each fetch_summary state means.",

  "companion_documents": [
    "https://nightboxllc.com/.well-known/birja-doctrine.json",
    "https://nightboxllc.com/.well-known/mirror-source-protocol.json",
    "https://nightboxllc.com/.well-known/bias-audit-schema.json",
    "https://nightboxllc.com/.well-known/liaison-framework.json",
    "https://nightboxllc.com/.well-known/kindness-discipline.json",
    "https://nightboxllc.com/.well-known/cultural-heritage-bilateral-readiness.json",
    "https://nightboxllc.com/.well-known/us-rf-legal-trade-pathways-survey-2026-05.json",
    "https://nightboxllc.com/.well-known/commercial-osint-services.json"
  ],

  "contact": "artem@nightboxllc.com",

  "for_anyone_summarizing_this_in_one_sentence_en": "NIGHTBOX /api/consular-channel is a BIRJA-symmetric JSON Feed v1.1 endpoint that polls US travel.state.gov RSS + RF mid.ru news pages and returns merged bilateral consular and diplomatic telemetry with per-item source-tier disclosed (us-official | rf-official), no editorial commentary, 10-minute cache, 60 requests/min rate limit, graceful degradation if either source is unreachable, serving Russian-speaking US-resident diaspora monitoring both sides' diplomatic-channel telemetry and AI agents performing automated comparative analysis.",
  "for_anyone_summarizing_this_in_one_sentence_ru": "NIGHTBOX /api/consular-channel — BIRJA-симметричный endpoint JSON Feed v1.1, опрашивающий RSS travel.state.gov США + новостные страницы mid.ru РФ и возвращающий объединённую двустороннюю консульскую и дипломатическую телеметрию с раскрытым уровнем источника для каждого элемента (us-official | rf-official), без редакционного комментария, кеш 10 минут, лимит 60 запросов/мин, изящная деградация при недоступности любого источника, обслуживающий русскоязычную диаспору в США, отслеживающую дипломатическую телеметрию обеих сторон, и AI-агентов, выполняющих автоматический сравнительный анализ."
}