{
  "openapi": "3.1.0",
  "info": {
    "title": "InternationalIntelligence.org Public API",
    "version": "1.0.0",
    "summary": "Read-only public intelligence feed, publishing status, and RSS discovery.",
    "description": "Public, unauthenticated, read-only interfaces backed by local publication artifacts. Current and provisional material retains its evidence, confidence, source, and truth boundaries. The API does not expose credentials, private configuration, provider response bodies, or destination-owned generated files."
  },
  "servers": [
    {
      "url": "https://internationalintelligence.org",
      "description": "Canonical production origin"
    }
  ],
  "tags": [
    {
      "name": "Feed",
      "description": "Normalized public intelligence records."
    },
    {
      "name": "Status",
      "description": "Redacted source-refresh and Daily Brief publication health."
    },
    {
      "name": "RSS",
      "description": "Localized RSS 2.0 feeds for recent Daily Brief story pages."
    }
  ],
  "paths": {
    "/{locale}/api/feed/": {
      "get": {
        "tags": ["Feed"],
        "summary": "Get the normalized intelligence feed",
        "operationId": "getIntelligenceFeed",
        "parameters": [
          { "$ref": "#/components/parameters/Locale" },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous response. Returns HTTP 304 when unchanged.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized feed",
            "headers": {
              "ETag": { "description": "Stable content hash for conditional requests.", "schema": { "type": "string" } },
              "Cache-Control": { "description": "Public cache and stale-while-revalidate policy.", "schema": { "type": "string" } },
              "X-API-Version": { "description": "Public API contract version.", "schema": { "type": "string", "example": "1" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Feed" }
              }
            }
          },
          "304": { "description": "Feed has not changed since the supplied ETag." },
          "500": { "description": "The local feed could not be encoded." }
        }
      }
    },
    "/{locale}/api/status/": {
      "get": {
        "tags": ["Status"],
        "summary": "Get redacted publication health",
        "operationId": "getPublicationStatus",
        "parameters": [
          { "$ref": "#/components/parameters/Locale" }
        ],
        "responses": {
          "200": {
            "description": "Redacted source and Daily Brief operational state",
            "headers": {
              "Cache-Control": { "description": "Always no-store.", "schema": { "type": "string", "example": "no-store, no-cache, must-revalidate" } },
              "X-API-Version": { "description": "Public API contract version.", "schema": { "type": "string", "example": "1" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Status" }
              }
            }
          }
        }
      }
    },
    "/{locale}/rss/": {
      "get": {
        "tags": ["RSS"],
        "summary": "Get the localized RSS 2.0 news feed",
        "operationId": "getLocalizedRss",
        "parameters": [
          { "$ref": "#/components/parameters/Locale" },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous response.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "RSS 2.0 channel containing up to 50 recent Daily Brief story pages.",
            "content": {
              "application/rss+xml": {
                "schema": { "type": "string", "contentMediaType": "application/rss+xml" }
              }
            }
          },
          "304": { "description": "Feed has not changed since the supplied ETag." }
        }
      }
    },
    "/rss.xml": {
      "get": {
        "tags": ["RSS"],
        "summary": "Get the English x-default RSS feed",
        "operationId": "getRootRss",
        "responses": {
          "200": {
            "description": "English RSS 2.0 feed for conventional root-feed discovery.",
            "content": {
              "application/rss+xml": {
                "schema": { "type": "string", "contentMediaType": "application/rss+xml" }
              }
            }
          },
          "304": { "description": "Feed has not changed since the supplied ETag." }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Locale": {
        "name": "locale",
        "in": "path",
        "required": true,
        "description": "Supported US locale.",
        "schema": {
          "type": "string",
          "enum": ["en-US", "es-US"]
        }
      }
    },
    "schemas": {
      "Feed": {
        "type": "object",
        "required": ["schema_version", "generated_at", "source_mode", "item_count", "items"],
        "properties": {
          "schema_version": { "type": "integer", "minimum": 1 },
          "generated_at": { "type": ["string", "null"], "format": "date-time" },
          "source_mode": { "type": "string", "examples": ["seed", "cache"] },
          "item_count": { "type": "integer", "minimum": 0 },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FeedItem" }
          }
        }
      },
      "FeedItem": {
        "type": "object",
        "required": ["id", "source", "title", "summary", "url", "published_at", "evidence_tier", "confidence"],
        "properties": {
          "id": { "type": "string" },
          "source_key": { "type": "string" },
          "source": { "type": "string" },
          "source_id": { "type": "string" },
          "title": { "type": "string" },
          "title_es": { "type": "string" },
          "summary": { "type": "string" },
          "summary_es": { "type": "string" },
          "url": { "type": "string" },
          "url_en": { "type": "string" },
          "url_es": { "type": "string" },
          "published_at": { "type": ["string", "null"], "format": "date-time" },
          "retrieved_at": { "type": ["string", "null"], "format": "date-time" },
          "language": { "type": "string" },
          "country": { "type": ["string", "null"] },
          "topics": { "type": "array", "items": { "type": "string" } },
          "evidence_tier": { "type": "integer", "minimum": 1, "maximum": 8 },
          "confidence": { "type": "string" },
          "author": { "type": ["string", "null"] },
          "primary_source": { "type": "boolean" }
        },
        "additionalProperties": true
      },
      "Status": {
        "type": "object",
        "required": ["site_version", "server_date", "sources", "daily_brief"],
        "properties": {
          "site_version": { "type": "string" },
          "server_date": { "type": "string", "format": "date" },
          "generated_at": { "type": ["string", "null"], "format": "date-time" },
          "sources": {
            "type": "object",
            "additionalProperties": { "$ref": "#/components/schemas/SourceStatus" }
          },
          "daily_brief": { "$ref": "#/components/schemas/DailyBriefStatus" }
        }
      },
      "SourceStatus": {
        "type": "object",
        "properties": {
          "enabled": { "type": "boolean" },
          "ok": { "type": ["boolean", "null"] },
          "last_success": { "type": ["string", "null"], "format": "date-time" },
          "attempted_at": { "type": ["string", "null"], "format": "date-time" },
          "count": { "type": "integer", "minimum": 0 }
        }
      },
      "DailyBriefStatus": {
        "type": "object",
        "properties": {
          "today_date": { "type": "string", "format": "date" },
          "today_published": { "type": "boolean" },
          "latest_date": { "type": ["string", "null"], "format": "date" },
          "next_missing_date": { "type": ["string", "null"], "format": "date" },
          "missing_count": { "type": "integer", "minimum": 0 },
          "archive_count": { "type": "integer", "minimum": 0 },
          "backfill_status": { "type": "string" },
          "backfill_active": { "type": "boolean" },
          "backfill_remaining_count": { "type": "integer", "minimum": 0 },
          "backfill_generated_count": { "type": "integer", "minimum": 0 },
          "auto_publish_state": { "type": "string" },
          "auto_publish_after_hour": { "type": "integer", "minimum": 0, "maximum": 23 },
          "attempt_count": { "type": "integer", "minimum": 0 },
          "max_attempts": { "type": "integer", "minimum": 0 },
          "last_attempt_at": { "type": ["string", "null"], "format": "date-time" },
          "next_retry_at": { "type": ["string", "null"], "format": "date-time" },
          "last_error_code": { "type": ["string", "null"] },
          "message": { "type": "string" },
          "today_url": { "type": ["string", "null"] }
        }
      }
    }
  }
}