{
  "openapi": "3.0.3",
  "info": {
    "title": "APITube News API",
    "description": "Real-time news API providing access to articles from 300,000+ verified sources worldwide in 60+ languages. Supports full-text search, sentiment analysis, entity recognition, and advanced filtering.",
    "version": "1.0.0",
    "contact": {
      "name": "APITube Support",
      "url": "https://apitube.io/contact"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "x-logo": {
      "url": "https://apitube.io/images/logo.svg"
    }
  },
  "servers": [
    {
      "url": "https://api.apitube.io",
      "description": "Production API server"
    }
  ],
  "externalDocs": {
    "description": "Full APITube documentation",
    "url": "https://docs.apitube.io"
  },
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "ApiKeyQuery": []
    }
  ],
  "paths": {
    "/v1/news/everything": {
      "get": {
        "summary": "Search all articles",
        "description": "Search and filter articles from all sources. Supports keyword search, sentiment analysis, entity filtering, language/country filtering, date ranges, and sorting.",
        "operationId": "getEverything",
        "tags": ["News"],
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "description": "Your API key (alternative to X-API-Key header)",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "title",
            "in": "query",
            "description": "Search in article titles. Supports keywords and exact phrases (in quotes).",
            "required": false,
            "schema": { "type": "string" },
            "example": "artificial intelligence"
          },
          {
            "name": "language.code",
            "in": "query",
            "description": "Filter by language (ISO 639-1 code). Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "en"
          },
          {
            "name": "source.country.code",
            "in": "query",
            "description": "Filter by source country (ISO 3166-1 alpha-2). Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "us"
          },
          {
            "name": "source.domain",
            "in": "query",
            "description": "Filter by source domain. Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "theguardian.com"
          },
          {
            "name": "category.id",
            "in": "query",
            "description": "Filter by IPTC category ID. Up to 3 comma-separated values (OR logic).",
            "required": false,
            "schema": { "type": "string" },
            "example": "medtop:15000000"
          },
          {
            "name": "topic.id",
            "in": "query",
            "description": "Filter by topic ID. Up to 3 comma-separated values (OR logic).",
            "required": false,
            "schema": { "type": "integer" },
            "example": 1
          },
          {
            "name": "industry.id",
            "in": "query",
            "description": "Filter by industry ID. Up to 3 comma-separated values (OR logic).",
            "required": false,
            "schema": { "type": "string" },
            "example": "400"
          },
          {
            "name": "entity.id",
            "in": "query",
            "description": "Filter by named entity ID. Up to 3 comma-separated values (OR logic).",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "person.name",
            "in": "query",
            "description": "Filter articles mentioning a specific person. Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "Elon Musk"
          },
          {
            "name": "organization.name",
            "in": "query",
            "description": "Filter articles mentioning a specific organization. Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "Google"
          },
          {
            "name": "brand.name",
            "in": "query",
            "description": "Filter articles mentioning a specific brand. Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "Nike"
          },
          {
            "name": "location.name",
            "in": "query",
            "description": "Filter by geographic location mentioned in the article. Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "Tokyo"
          },
          {
            "name": "sentiment.overall.polarity",
            "in": "query",
            "description": "Filter by sentiment polarity.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            }
          },
          {
            "name": "sentiment.overall.score.min",
            "in": "query",
            "description": "Minimum overall sentiment score (-1 to 1).",
            "required": false,
            "schema": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 }
          },
          {
            "name": "sentiment.overall.score.max",
            "in": "query",
            "description": "Maximum overall sentiment score (-1 to 1).",
            "required": false,
            "schema": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 }
          },
          {
            "name": "entity.sentiment.polarity",
            "in": "query",
            "description": "Filter by sentiment polarity toward the entity. Combine with entity.id or *.name; standalone matches any entity with that sentiment.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            }
          },
          {
            "name": "entity.sentiment.score.min",
            "in": "query",
            "description": "Minimum sentiment score toward the entity (-1 to 1).",
            "required": false,
            "schema": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 }
          },
          {
            "name": "entity.sentiment.score.max",
            "in": "query",
            "description": "Maximum sentiment score toward the entity (-1 to 1).",
            "required": false,
            "schema": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 }
          },
          {
            "name": "published_at.start",
            "in": "query",
            "description": "Start of publication date range. ISO 8601 (YYYY-MM-DD) or relative (e.g. NOW-7DAYS).",
            "required": false,
            "schema": { "type": "string" },
            "example": "2024-01-01"
          },
          {
            "name": "published_at.end",
            "in": "query",
            "description": "End of publication date range. ISO 8601 (YYYY-MM-DD) or relative (e.g. NOW).",
            "required": false,
            "schema": { "type": "string" },
            "example": "NOW"
          },
          {
            "name": "sort.by",
            "in": "query",
            "description": "Field to sort results by.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["published_at", "relevance", "engagement", "quality", "controversy", "trust", "id", "new", "created_at", "source.rank.opr", "sentiment.overall.score", "sentiment.title.score", "sentiment.body.score", "read_time", "sentences_count", "paragraphs_count", "characters_count", "media.images.count", "media.videos.count", "media.images.width.min", "media.images.width.max", "media.images.height.min", "media.images.height.max", "media_richness", "shares.facebook.min", "shares.facebook.max", "shares.twitter.min", "shares.twitter.max", "shares.reddit.min", "shares.reddit.max"]
            },
            "example": "published_at"
          },
          {
            "name": "sort.order",
            "in": "query",
            "description": "Sort direction.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["asc", "desc"],
              "default": "desc"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200).",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          },
          {
            "name": "source.bias",
            "in": "query",
            "description": "Filter by media bias classification. Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string", "enum": ["left", "center", "right"] }
          },
          {
            "name": "has_image",
            "in": "query",
            "description": "Filter articles that have at least one image (1=yes, 0=no).",
            "required": false,
            "schema": { "type": "integer", "enum": [0, 1] }
          },
          {
            "name": "is_breaking",
            "in": "query",
            "description": "Filter for breaking news only (1=yes, 0=no).",
            "required": false,
            "schema": { "type": "integer", "enum": [0, 1] }
          },
          {
            "name": "is_premium_source",
            "in": "query",
            "description": "Filter for premium sources with Open Page Rank >= 6 (1=yes).",
            "required": false,
            "schema": { "type": "integer", "enum": [0, 1] }
          },
          {
            "name": "fl",
            "in": "query",
            "description": "Comma-separated list of fields to return. Supports dot notation for nested fields.",
            "required": false,
            "schema": { "type": "string" },
            "example": "id,title,source.domain,published_at"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with paginated list of articles",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/NewsListResponse" },
                "example": {
                  "status": "ok",
                  "limit": 10,
                  "page": 1,
                  "has_next_pages": true,
                  "next_page": "https://api.apitube.io/v1/news/everything?page=2&per_page=10",
                  "has_previous_page": false,
                  "previous_page": "",
                  "request_id": "550e8400-e29b-41d4-a716-446655440000",
                  "results": []
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/news/top-headlines": {
      "get": {
        "summary": "Get top headlines",
        "description": "Retrieve the most prominent and trending news articles. Supports the same filtering options as /v1/news/everything with results ranked by editorial prominence.",
        "operationId": "getTopHeadlines",
        "tags": ["News"],
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "description": "Your API key (alternative to X-API-Key header)",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "language.code",
            "in": "query",
            "description": "Filter by language (ISO 639-1 code). Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "en"
          },
          {
            "name": "source.country.code",
            "in": "query",
            "description": "Filter by source country (ISO 3166-1 alpha-2). Up to 3 comma-separated values.",
            "required": false,
            "schema": { "type": "string" },
            "example": "us"
          },
          {
            "name": "category.id",
            "in": "query",
            "description": "Filter by IPTC category ID.",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "topic.id",
            "in": "query",
            "description": "Filter by topic ID.",
            "required": false,
            "schema": { "type": "integer" }
          },
          {
            "name": "published_at.start",
            "in": "query",
            "description": "Start of publication date range (ISO 8601 or relative).",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "published_at.end",
            "in": "query",
            "description": "End of publication date range (ISO 8601 or relative).",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200).",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with top headline articles",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/NewsListResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/news/trends": {
      "get": {
        "summary": "Get trending topics and entities",
        "description": "Aggregate and analyze trending values across specific fields such as entities, categories, topics, industries, and sources. Supports time-series analysis and comparison with previous periods.",
        "operationId": "getTrends",
        "tags": ["News"],
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "description": "Your API key (alternative to X-API-Key header)",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "field",
            "in": "query",
            "description": "Fields to aggregate on. Required.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["entity.id", "category.id", "topic.id", "industry.id", "source.id"]
            },
            "example": "entity.id"
          },
          {
            "name": "language.code",
            "in": "query",
            "description": "Filter by language.",
            "required": false,
            "schema": { "type": "string" },
            "example": "en"
          },
          {
            "name": "published_at.start",
            "in": "query",
            "description": "Start of date range.",
            "required": false,
            "schema": { "type": "string" },
            "example": "NOW-7DAYS"
          },
          {
            "name": "published_at.end",
            "in": "query",
            "description": "End of date range.",
            "required": false,
            "schema": { "type": "string" },
            "example": "NOW"
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Top results to return per field (1–100).",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort trending results by.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["count", "value", "growth_rate", "change", "trending_score"],
              "default": "count"
            }
          },
          {
            "name": "order",
            "in": "query",
            "description": "Sort order.",
            "required": false,
            "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }
          },
          {
            "name": "mincount",
            "in": "query",
            "description": "Minimum article count for a value to be included.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1 }
          },
          {
            "name": "trending",
            "in": "query",
            "description": "Enable trending analysis with time-series history.",
            "required": false,
            "schema": { "type": "boolean" }
          },
          {
            "name": "trending_days",
            "in": "query",
            "description": "Number of days to analyze for trending (7–30).",
            "required": false,
            "schema": { "type": "integer", "minimum": 7, "maximum": 30, "default": 14 }
          },
          {
            "name": "compare",
            "in": "query",
            "description": "Enable comparison with a previous time period.",
            "required": false,
            "schema": { "type": "boolean" }
          },
          {
            "name": "compare_window",
            "in": "query",
            "description": "Comparison window size.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["24HOURS", "7DAYS", "1WEEK", "2w", "1m"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trending aggregation results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TrendsResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/balance": {
      "get": {
        "summary": "Get account balance and quota",
        "description": "Retrieve current API usage, remaining quota, and subscription plan information for the authenticated account.",
        "operationId": "getBalance",
        "tags": ["Account"],
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "description": "Your API key (alternative to X-API-Key header)",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Account balance and quota information",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BalanceResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/suggest/entities": {
      "get": {
        "summary": "Autocomplete entity search",
        "description": "Search for entity IDs (people, organizations, brands, locations) by name. Use to resolve entity names to IDs before filtering news results.",
        "operationId": "suggestEntities",
        "tags": ["Utilities"],
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "description": "Your API key (alternative to X-API-Key header)",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "prefix",
            "in": "query",
            "description": "Search prefix for entity name. Required.",
            "required": true,
            "schema": { "type": "string" },
            "example": "Apple"
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching entities",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EntitySuggestResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key passed as a request header"
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key",
        "description": "API key passed as a query parameter"
      }
    },
    "schemas": {
      "Article": {
        "type": "object",
        "description": "A news article object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique article identifier"
          },
          "href": {
            "type": "string",
            "format": "uri",
            "description": "Original article URL"
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "description": "Publication timestamp (ISO 8601)"
          },
          "title": {
            "type": "string",
            "description": "Article headline"
          },
          "description": {
            "type": "string",
            "description": "Brief article summary or lead paragraph"
          },
          "body": {
            "type": "string",
            "description": "Full article body in plaintext"
          },
          "body_html": {
            "type": "string",
            "description": "Full article body in HTML"
          },
          "language": {
            "type": "string",
            "description": "Article language (ISO 639-1 code)",
            "example": "en"
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "Primary article image URL"
          },
          "author": {
            "type": "object",
            "properties": {
              "id": { "type": "integer", "nullable": true },
              "name": { "type": "string" },
              "links": {
                "type": "object",
                "properties": {
                  "self": { "type": "string", "description": "Link to journalist endpoint" }
                }
              }
            }
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "categories": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Category" }
          },
          "topics": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Topic" }
          },
          "industries": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Industry" }
          },
          "entities": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Entity" }
          },
          "sentiment": {
            "$ref": "#/components/schemas/Sentiment"
          },
          "summary": {
            "type": "array",
            "description": "Extractive summary sentences with per-sentence sentiment",
            "items": {
              "type": "object",
              "properties": {
                "sentence": { "type": "string" },
                "sentiment": {
                  "type": "object",
                  "properties": {
                    "score": { "type": "number", "format": "float" },
                    "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"] }
                  }
                }
              }
            }
          },
          "keywords": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Extracted keywords from the article"
          },
          "media": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": { "type": "string", "format": "uri" },
                "type": { "type": "string", "enum": ["image", "video"] }
              }
            }
          },
          "story": {
            "type": "object",
            "description": "Related story cluster this article belongs to",
            "properties": {
              "id": { "type": "integer" },
              "uri": { "type": "string" }
            },
            "nullable": true
          },
          "is_breaking": {
            "type": "boolean",
            "description": "Whether this is a breaking news article"
          },
          "is_duplicate": {
            "type": "boolean",
            "description": "Whether this article is a near-duplicate of another"
          },
          "is_free": {
            "type": "boolean",
            "description": "Whether the article is freely accessible (not paywalled)"
          },
          "read_time": {
            "type": "integer",
            "description": "Estimated reading time in minutes"
          },
          "words_count": {
            "type": "integer",
            "description": "Total word count of the article"
          },
          "sentences_count": {
            "type": "integer",
            "description": "Total sentence count"
          },
          "paragraphs_count": {
            "type": "integer",
            "description": "Total paragraph count"
          },
          "characters_count": {
            "type": "integer",
            "description": "Total character count"
          }
        }
      },
      "Source": {
        "type": "object",
        "description": "News source / publisher information",
        "properties": {
          "id": { "type": "integer" },
          "domain": { "type": "string", "example": "techcrunch.com" },
          "home_page_url": { "type": "string", "format": "uri" },
          "type": { "type": "string", "enum": ["news", "blog"] },
          "bias": { "type": "string", "enum": ["left", "center", "right"] },
          "rankings": {
            "type": "object",
            "properties": {
              "opr": { "type": "integer", "description": "Open Page Rank (0–7)" }
            }
          },
          "location": {
            "type": "object",
            "properties": {
              "country_name": { "type": "string" },
              "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2" }
            }
          },
          "favicon": { "type": "string", "format": "uri" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "score": { "type": "number", "format": "float", "description": "Confidence score (0–1)" },
          "taxonomy": { "type": "string" },
          "links": {
            "type": "object",
            "properties": { "self": { "type": "string" } }
          }
        }
      },
      "Topic": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "score": { "type": "number", "format": "float", "description": "Confidence score (0–1)" },
          "links": {
            "type": "object",
            "properties": { "self": { "type": "string" } }
          }
        }
      },
      "Industry": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "links": {
            "type": "object",
            "properties": { "self": { "type": "string" } }
          }
        }
      },
      "Entity": {
        "type": "object",
        "description": "Named entity (person, organization, brand, location) mentioned in the article",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "type": { "type": "string", "enum": ["human", "location", "organization", "brand"] },
          "frequency": { "type": "integer", "description": "Number of times this entity is mentioned" },
          "sentiment": {
            "type": "object",
            "description": "Sentiment expressed toward this entity, aggregated across its mentions",
            "properties": {
              "score": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 },
              "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"] },
              "mentions": {
                "type": "object",
                "description": "Per-mention polarity counts",
                "properties": {
                  "positive": { "type": "integer" },
                  "neutral": { "type": "integer" },
                  "negative": { "type": "integer" }
                }
              }
            }
          },
          "links": {
            "type": "object",
            "properties": {
              "self": { "type": "string" },
              "wikipedia": { "type": "string" },
              "wikidata": { "type": "string" }
            }
          },
          "metadata": {
            "type": "object",
            "description": "Entity-type-specific metadata (varies by type)"
          }
        }
      },
      "Sentiment": {
        "type": "object",
        "description": "Sentiment analysis for the article",
        "properties": {
          "overall": {
            "type": "object",
            "properties": {
              "score": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 },
              "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"] }
            }
          },
          "title": {
            "type": "object",
            "properties": {
              "score": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 },
              "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"] }
            }
          },
          "body": {
            "type": "object",
            "properties": {
              "score": { "type": "number", "format": "float", "minimum": -1, "maximum": 1 },
              "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"] }
            }
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "limit": { "type": "integer" },
          "page": { "type": "integer" },
          "has_next_pages": { "type": "boolean" },
          "next_page": { "type": "string" },
          "has_previous_page": { "type": "boolean" },
          "previous_page": { "type": "string" },
          "path": { "type": "string" },
          "request_id": { "type": "string", "format": "uuid" },
          "export": {
            "type": "object",
            "description": "Export URLs for various formats",
            "properties": {
              "json": { "type": "string" },
              "xlsx": { "type": "string" },
              "csv": { "type": "string" },
              "tsv": { "type": "string" },
              "xml": { "type": "string" },
              "rss": { "type": "string" },
              "parquet": { "type": "string" },
              "jsonl": { "type": "string" }
            }
          }
        }
      },
      "NewsListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/Pagination" },
          {
            "type": "object",
            "required": ["results"],
            "properties": {
              "results": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/Article" }
              }
            }
          }
        ]
      },
      "TrendsResponse": {
        "type": "object",
        "description": "Aggregated trends for a single field. Requesting several fields keys `trends` by field name instead.",
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "field": { "type": "string", "example": "category.id" },
          "per_page": { "type": "integer", "example": 10 },
          "offset": { "type": "integer", "example": 0 },
          "total_count": { "type": "integer", "description": "How many distinct values matched" },
          "total_articles": { "type": "integer", "description": "How many articles the aggregation covered" },
          "sort": { "type": "string", "example": "count" },
          "order": { "type": "string", "example": "desc" },
          "mincount": { "type": "integer", "example": 1 },
          "trends": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "object",
                  "description": "The aggregated value, enriched from the reference tables (id/name/taxonomy).",
                  "properties": {
                    "id": { "type": "string", "example": "medtop:04000000" },
                    "name": { "type": "string", "example": "economy, business and finance" },
                    "taxonomy": { "type": "string", "example": "iptc_mediatopics" }
                  }
                },
                "count": { "type": "integer" },
                "percentage": { "type": "number", "format": "float" },
                "growth_rate": { "type": "number", "format": "float" },
                "trending_score": { "type": "number", "format": "float", "description": "Only with trending=1" }
              }
            }
          }
        }
      },
      "BalanceResponse": {
        "type": "object",
        "properties": {
          "api_key": { "type": "string", "description": "The API key the balance belongs to", "example": "api_live_abc123..." },
          "points": { "type": "integer", "description": "Remaining request quota (points)", "example": 48500 },
          "plan": { "type": "string", "description": "Subscription plan the key resolves to", "example": "basic" }
        }
      },
      "EntitySuggestResponse": {
        "type": "array",
        "description": "Array of matching entities — this endpoint returns a bare array, not a status envelope.",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "integer" },
            "name": { "type": "string" },
            "type": {
              "type": "string",
              "enum": [
                "person",
                "location",
                "organization",
                "brand",
                "product",
                "natural-disaster",
                "disease",
                "event",
                "sport",
                "unknown"
              ]
            },
            "links": {
              "type": "object",
              "properties": {
                "self": { "type": "string" },
                "wikipedia": { "type": "string" },
                "wikidata": { "type": "string" }
              }
            },
            "metadata": { "type": "object", "description": "Entity metadata (aliases, founded, industry, ...)" }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["status", "code", "message"],
        "properties": {
          "status": { "type": "integer", "description": "HTTP status code" },
          "code": { "type": "string", "description": "Machine-readable error identifier" },
          "message": { "type": "string", "description": "Human-readable error description" },
          "links": {
            "type": "object",
            "properties": {
              "about": { "type": "string", "description": "Documentation URL for this error" }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": {
              "status": 401,
              "code": "unauthorized",
              "message": "Invalid or missing API key. Provide it via X-API-Key header or api_key query parameter."
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "Quota exhausted or plan upgrade required",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "News",
      "description": "Endpoints for searching and retrieving news articles"
    },
    {
      "name": "Account",
      "description": "Account management and quota information"
    },
    {
      "name": "Utilities",
      "description": "Helper endpoints for building queries"
    }
  ]
}
