{
  "openapi": "3.0.3",
  "info": {
    "title": "NewsSpoiler JSON API",
    "version": "v1",
    "description": "Read-only JSON API for NewsSpoiler public-safe structured news snapshot data. The API provides articles, image articles, search, single article lookup, related articles, topic and entity directories, topic/entity article lists, topic/entity velocity, trending categories, trending sources, and trending locations. Operational ingestion systems remain internal to the platform. Widget delivery is handled separately by https://widgets.newsspoiler.com."
  },
  "servers": [
    {
      "url": "https://api.newsspoiler.com/api/v1",
      "description": "NewsSpoiler v1 API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyQuery": []
    },
    {}
  ],
  "tags": [
    {
      "name": "Status"
    },
    {
      "name": "Articles"
    },
    {
      "name": "Search"
    },
    {
      "name": "Topics & Entities"
    },
    {
      "name": "Trending"
    },
    {
      "name": "Documentation"
    }
  ],
  "paths": {
    "/status.php": {
      "get": {
        "tags": ["Status"],
        "summary": "API status",
        "description": "Returns API status and public snapshot summary.",
        "responses": {
          "200": {
            "description": "Status response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/docs.php": {
      "get": {
        "tags": ["Documentation"],
        "summary": "JSON API documentation",
        "description": "Returns a compact JSON documentation payload for the current v1 API.",
        "responses": {
          "200": {
            "description": "Documentation response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/articles.php": {
      "get": {
        "tags": ["Articles"],
        "summary": "List articles",
        "description": "Returns public-safe article snapshots.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/SourceDomain"
          },
          {
            "$ref": "#/components/parameters/City"
          },
          {
            "$ref": "#/components/parameters/StateRegion"
          },
          {
            "$ref": "#/components/parameters/HasImage"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Article list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/images.php": {
      "get": {
        "tags": ["Articles"],
        "summary": "List image articles",
        "description": "Returns public-safe article snapshots that include image URLs.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Image article list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleListEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/search.php": {
      "get": {
        "tags": ["Search"],
        "summary": "Search articles",
        "description": "Searches public-safe article snapshots across title, excerpt, source, category, and location fields.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query. Minimum 2 characters, maximum 120 characters.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/SourceDomain"
          },
          {
            "$ref": "#/components/parameters/City"
          },
          {
            "$ref": "#/components/parameters/StateRegion"
          },
          {
            "$ref": "#/components/parameters/HasImage"
          },
          {
            "$ref": "#/components/parameters/PublishedAfter"
          },
          {
            "$ref": "#/components/parameters/PublishedBefore"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/article.php": {
      "get": {
        "tags": ["Articles"],
        "summary": "Get one article",
        "description": "Returns a single public-safe article snapshot by public article id.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PublicId"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Single article",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/related.php": {
      "get": {
        "tags": ["Articles"],
        "summary": "Get related articles",
        "description": "Returns related public-safe article snapshots for a source article id.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PublicId"
          },
          {
            "$ref": "#/components/parameters/Limit25"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Related article list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/topics.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "List topics",
        "description": "Returns public-safe active topics.",
        "parameters": [
          {
            "$ref": "#/components/parameters/TopicType"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Topic list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/topic.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "Get one topic",
        "description": "Returns a single public-safe active topic by slug.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Slug"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Single topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/topic-articles.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "List topic articles",
        "description": "Returns public-safe article snapshots connected to a topic slug.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Slug"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Topic article list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/entities.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "List entities",
        "description": "Returns public-safe active entities.",
        "parameters": [
          {
            "$ref": "#/components/parameters/EntityType"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Entity list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/entity.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "Get one entity",
        "description": "Returns a single public-safe active entity by slug.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Slug"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Single entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/entity-articles.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "List entity articles",
        "description": "Returns public-safe article snapshots connected to an entity slug.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Slug"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Entity article list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/trending-topics.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "Trending topics",
        "description": "Returns public-safe topic velocity ranked by article count.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Window"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Trending topic list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VelocityListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/trending-entities.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "Trending entities",
        "description": "Returns public-safe entity velocity ranked by article count.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Window"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Trending entity list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VelocityListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/rising-topics.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "Rising topics",
        "description": "Returns public-safe rising topics ranked by velocity score.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Window"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Rising topic list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VelocityListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/rising-entities.php": {
      "get": {
        "tags": ["Topics & Entities"],
        "summary": "Rising entities",
        "description": "Returns public-safe rising entities ranked by velocity score.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Window"
          },
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Rising entity list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VelocityListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/trending-categories.php": {
      "get": {
        "tags": ["Trending"],
        "summary": "Trending categories",
        "description": "Returns trending public categories from snapshot articles.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Trending categories",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrendingListEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/trending-sources.php": {
      "get": {
        "tags": ["Trending"],
        "summary": "Trending sources",
        "description": "Returns trending public sources from snapshot articles.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Trending sources",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrendingListEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/trending-locations.php": {
      "get": {
        "tags": ["Trending"],
        "summary": "Trending locations",
        "description": "Returns trending public locations from snapshot articles.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit100"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Trending locations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrendingListEnvelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Optional bearer token for attribution and integration tracking."
      },
      "apiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key",
        "description": "Optional query parameter API key for attribution and integration tracking."
      }
    },
    "parameters": {
      "ApiKeyQuery": {
        "name": "api_key",
        "in": "query",
        "required": false,
        "description": "Optional API key for attribution and integration tracking.",
        "schema": {
          "type": "string",
          "maxLength": 255
        }
      },
      "Category": {
        "name": "category",
        "in": "query",
        "required": false,
        "description": "Category slug, such as gaming.",
        "schema": {
          "type": "string",
          "maxLength": 120
        }
      },
      "SourceDomain": {
        "name": "source_domain",
        "in": "query",
        "required": false,
        "description": "Publisher/source domain.",
        "schema": {
          "type": "string",
          "maxLength": 253
        }
      },
      "City": {
        "name": "city",
        "in": "query",
        "required": false,
        "description": "City filter.",
        "schema": {
          "type": "string",
          "maxLength": 100
        }
      },
      "StateRegion": {
        "name": "state_region",
        "in": "query",
        "required": false,
        "description": "State, region, or abbreviation filter.",
        "schema": {
          "type": "string",
          "maxLength": 100
        }
      },
      "HasImage": {
        "name": "has_image",
        "in": "query",
        "required": false,
        "description": "Whether to return articles with image URLs.",
        "schema": {
          "type": "boolean"
        }
      },
      "PublishedAfter": {
        "name": "published_after",
        "in": "query",
        "required": false,
        "description": "Return articles published at or after this timestamp.",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "PublishedBefore": {
        "name": "published_before",
        "in": "query",
        "required": false,
        "description": "Return articles published at or before this timestamp.",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "Limit100": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Result limit. Default 25, maximum 100.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        }
      },
      "Limit25": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Result limit. Default 10, maximum 25.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 25,
          "default": 10
        }
      },
      "PublicId": {
        "name": "id",
        "in": "query",
        "required": true,
        "description": "Public article id returned by article list responses.",
        "schema": {
          "type": "string",
          "pattern": "^[a-f0-9]{32}$"
        }
      },
      "Slug": {
        "name": "slug",
        "in": "query",
        "required": true,
        "description": "Public-safe topic or entity slug.",
        "schema": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{0,119}$"
        }
      },
      "TopicType": {
        "name": "type",
        "in": "query",
        "required": false,
        "description": "Optional topic type filter.",
        "schema": {
          "type": "string",
          "maxLength": 120
        }
      },
      "EntityType": {
        "name": "type",
        "in": "query",
        "required": false,
        "description": "Optional entity type filter, such as company, game, person, organization, platform, sports_team, location, or event.",
        "schema": {
          "type": "string",
          "maxLength": 120
        }
      },
      "Window": {
        "name": "window",
        "in": "query",
        "required": false,
        "description": "Velocity window. Defaults to 24h.",
        "schema": {
          "type": "string",
          "enum": ["1h", "6h", "24h", "7d"],
          "default": "24h"
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "required": ["request_id", "api_version"],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "api_version": {
            "type": "string",
            "example": "v1"
          },
          "query": {
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer"
          },
          "returned": {
            "type": "integer"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Article": {
        "type": "object",
        "required": ["id", "title", "url", "source", "category", "location"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Public article id."
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "image_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "source": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              },
              "domain": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "category": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              },
              "slug": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "location": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "nullable": true
              },
              "state_region": {
                "type": "string",
                "nullable": true
              },
              "country": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "snapshot_updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "TrendingItem": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "state_region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "Topic": {
        "type": "object",
        "required": ["slug", "display_name", "type"],
        "properties": {
          "slug": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Entity": {
        "type": "object",
        "required": ["slug", "display_name", "type"],
        "properties": {
          "slug": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "VelocityItem": {
        "type": "object",
        "required": ["slug", "display_name", "type", "article_count", "velocity_score", "trend_state", "window"],
        "properties": {
          "slug": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "article_count": {
            "type": "integer"
          },
          "velocity_score": {
            "type": "number",
            "format": "float"
          },
          "trend_state": {
            "type": "string",
            "enum": ["rising", "stable", "declining"]
          },
          "window": {
            "type": "string",
            "enum": ["1h", "6h", "24h", "7d"]
          }
        }
      },
      "ArticleListEnvelope": {
        "type": "object",
        "required": ["data", "pagination", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "ArticleEnvelope": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Article"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "VelocityListEnvelope": {
        "type": "object",
        "required": ["data", "pagination", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VelocityItem"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "TopicListEnvelope": {
        "type": "object",
        "required": ["data", "pagination", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Topic"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "TopicEnvelope": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Topic"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "EntityListEnvelope": {
        "type": "object",
        "required": ["data", "pagination", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Entity"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "EntityEnvelope": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Entity"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "ListEnvelope": {
        "type": "object",
        "required": ["data", "pagination", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "TrendingListEnvelope": {
        "type": "object",
        "required": ["data", "pagination", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrendingItem"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "DocsEnvelope": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "object"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["error", "meta"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      }
    }
  },
  "x-newsspoiler-notes": [
    "The JSON API provides public-safe structured news snapshot data.",
    "Operational ingestion systems remain internal to the platform.",
    "The JSON API is a read-only content delivery layer.",
    "Widget delivery is handled separately by https://widgets.newsspoiler.com."
  ]
}