{"openapi":"3.0.3","info":{"title":"Gnist Context — GDELT Global Events","description":"Global event intelligence — article search, event timelines, tone analysis, and geographic coverage from 150+ countries.\n\n- **MCP endpoint:** `https://context.gnist.ai/mcp/gdelt/`\n- **Toolkit page:** `/toolkits/gdelt`\n- **Full API spec:** `/api/openapi.json`\n- **Get an API key:** `/signup`","version":"1.0.0","contact":{"name":"GnistAI","url":"https://gnist.ai"}},"servers":[{"url":"https://context.gnist.ai","description":"Production"}],"paths":{"/rest/gdelt/search_articles":{"post":{"tags":["Media"],"summary":"search_articles","description":"Search global news articles across 150+ countries and 65+ languages.\n\nGDELT monitors news media worldwide, updated every 15 minutes. Returns\narticles with source, date, tone score, and thumbnail image.\n\nExamples:\n    search_articles(\"artificial intelligence\") → AI coverage from the last 24h\n    search_articles(\"oil prices\", timespan=\"7d\", sort=\"ToneDesc\") → positive oil news from the past week\n    search_articles(\"elections\", source_country=\"france\") → French election coverage\n\nReturns:\n    List of articles with URL, title, source, language, date, and tone score.","operationId":"gdelt_search_articles","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Search query — keywords, exact phrases in quotes, or GDELT syntax (e.g. \"climate change\", \"domain:bbc.com\").","type":"string"},"timespan":{"default":"24h","description":"Lookback window: \"24h\" (default), \"7d\", \"2w\", \"3m\". Max 3 months.","type":"string"},"max_results":{"default":25,"description":"Max articles to return (default 25, max 250).","type":"integer"},"sort":{"default":"HybridRel","description":"Sort order: \"HybridRel\" (relevance, default), \"DateDesc\", \"DateAsc\", \"ToneDesc\", \"ToneAsc\".","type":"string"},"source_country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter by source country (e.g. \"US\", \"france\", \"norway\"). Optional."},"source_lang":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter by source language (e.g. \"english\", \"spanish\"). Optional."}},"required":["query"],"type":"object"}}}}}},"/rest/gdelt/get_event_timeline":{"post":{"tags":["Media"],"summary":"get_event_timeline","description":"Get media coverage volume over time — tracks how a story rises and falls.\n\nReturns a time series of article counts matching the query. Useful for\ndetecting spikes in coverage, comparing before/after events, or monitoring\nongoing stories.\n\nExamples:\n    get_event_timeline(\"tariffs\") → tariff coverage over the past week\n    get_event_timeline(\"earthquake\", timespan=\"30d\") → earthquake coverage, monthly view\n    get_event_timeline(\"bitcoin\", smooth=5) → smoothed Bitcoin coverage trend\n\nReturns:\n    Time series with date and article volume at each time step.","operationId":"gdelt_get_event_timeline","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Search query — keywords or GDELT syntax.","type":"string"},"timespan":{"default":"7d","description":"Lookback window: \"7d\" (default), \"24h\", \"2w\", \"3m\". Max 3 months.","type":"string"},"smooth":{"default":0,"description":"Moving-average smoothing (0-30 time steps). 0 = no smoothing (default).","type":"integer"}},"required":["query"],"type":"object"}}}}}},"/rest/gdelt/get_tone_timeline":{"post":{"tags":["Media"],"summary":"get_tone_timeline","description":"Get media tone/sentiment over time for a topic.\n\nTone ranges from negative (critical/alarming) to positive (optimistic/favorable).\nMost news falls between -10 and +5. Tracks how public sentiment shifts\naround events, announcements, or crises.\n\nExamples:\n    get_tone_timeline(\"Federal Reserve\") → Fed sentiment over the past week\n    get_tone_timeline(\"Tesla\", timespan=\"30d\") → Tesla media sentiment, monthly\n    get_tone_timeline(\"war\", timespan=\"3m\", smooth=3) → smoothed conflict tone\n\nReturns:\n    Time series with date and tone score at each time step.","operationId":"gdelt_get_tone_timeline","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Search query — keywords or GDELT syntax.","type":"string"},"timespan":{"default":"7d","description":"Lookback window: \"7d\" (default), \"24h\", \"2w\", \"3m\". Max 3 months.","type":"string"},"smooth":{"default":0,"description":"Moving-average smoothing (0-30 time steps). 0 = no smoothing (default).","type":"integer"}},"required":["query"],"type":"object"}}}}}},"/rest/gdelt/get_source_country_breakdown":{"post":{"tags":["Media"],"summary":"get_source_country_breakdown","description":"Get which countries' media are covering a topic, ranked by volume.\n\nShows where news about a topic originates from — which countries'\nmedia outlets are writing about it most. Useful for understanding\nregional interest and geographic spread of coverage.\n\nExamples:\n    get_source_country_breakdown(\"trade war\") → which countries cover trade war most\n    get_source_country_breakdown(\"AI regulation\", timespan=\"7d\") → AI regulation coverage by country\n    get_source_country_breakdown(\"climate summit\") → which nations' media cover climate talks\n\nReturns:\n    List of countries sorted by coverage volume (highest first).","operationId":"gdelt_get_source_country_breakdown","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Search query — keywords or GDELT syntax.","type":"string"},"timespan":{"default":"24h","description":"Lookback window: \"24h\" (default), \"7d\", \"3m\". Max 3 months.","type":"string"}},"required":["query"],"type":"object"}}}}}},"/rest/gdelt/report_feedback":{"post":{"tags":["Media"],"summary":"report_feedback","description":"Report a bug, feature request, or general feedback for this data source.\n\nUse this when something doesn't work as expected, when you'd like\na new feature, or when you have suggestions for improvement.\n\nArgs:\n    feedback: Describe the issue or suggestion.\n    feedback_type: One of 'bug', 'feature_request', or 'general'.","operationId":"gdelt_report_feedback","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"feedback":{"type":"string"},"feedback_type":{"default":"general","type":"string"}},"required":["feedback"],"type":"object"}}}}}}},"tags":[{"name":"Media","description":"Data sources: Media"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"gnist-api-key","description":"API key passed via request header."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"gnist_api_key","description":"API key passed via query parameter."}}}}