Skip to main content

​
API Documentation Guide

This guide explains how the GDELT Cloud developer API documentation is structured and maintained.

​
Overview

GDELT Cloud uses Mintlify as its documentation platform. The docs expose two API reference tabs:
  • V2 API Reference: generated from gdelt-cloud-docs/api-reference/openapi-v2.json
  • V1 API Reference: legacy specs generated from gdelt-cloud-docs/api-reference/openapi*.json
The v2 spec is hand-maintained to match the clean public product contract. The v1 specs are maintained for existing direct API users.

​
Developer API — What We Document

The public docs expose API Key-authenticated /api/v2/* endpoints plus supported legacy /api/v1/* endpoints. Internal browser/session APIs (/api/public/*, /api/dashboard/*, etc.) are intentionally excluded.

​
v2 endpoints documented

MethodPathDescription
GET/api/v2/eventsList generated structured Events
GET/api/v2/events/{event_id}Fetch a known Event
GET/api/v2/events/summaryEvent rollups and trends
GET/api/v2/storiesList generated clustered Stories
GET/api/v2/stories/{story_id}Fetch a known Story
GET/api/v2/stories/{story_id}/articlesPaginated Story articles
GET/api/v2/stories/summaryStory rollups and trends
GET/api/v2/entitiesDiscover Entities
GET/api/v2/entities/{entity_id}Fetch an Entity profile
GET/api/v2/geo/admin1Country-scoped admin1 discovery
GET/api/v2/energy/assetsSearch GEM Energy assets
GET/api/v2/energy/assets/summaryEnergy asset rollups
GET/api/v2/energy/assets/mapEnergy map aggregate/fine rows
GET/api/v2/energy/assets/{tracker}/{gem_id}Fetch a known Energy asset

​
v1 endpoints documented

MethodPathDescription
GET/api/v1/media-eventsList top media event clusters
GET/api/v1/media-events/clusterGet articles in a specific cluster
GET/api/v1/entityLook up a named entity (GDELT GKG)
GET/api/v1/entity-gegLook up a GEG entity (enhanced graph)
GET/api/v1/domainLook up a news domain/source
GET/api/v1/conflict-eventsList legacy Conflict events

​
Regenerating the OpenAPI Spec

When you add, remove, or change a /api/v1/* endpoint, regenerate the v1 specs by running: 
python3 scripts/build_openapi.py
This script lives at scripts/build_openapi.py and writes to the v1 OpenAPI files under gdelt-cloud-docs/api-reference/. When you add, remove, or change a /api/v2/* endpoint, update api-reference/openapi-v2.json and the overview page api-reference/v2.mdx in the same change. The v2 docs must remain testable in Mintlify’s API playground.

​
What the script contains

  • All 5 endpoint definitions with full query parameter schemas
  • ApiKeyAuth security scheme (Bearer gdelt_sk_* format)
  • Standard response schemas (200 success, 401/403/429/500 errors)
  • Server definition pointing to https://gdeltcloud.com

​
When to run it

  • After adding a new /api/v1/* endpoint
  • After changing query parameters on an existing endpoint
  • After changing response shapes
  • After changing authentication or error behavior

​
Documentation File Structure

gdelt-cloud-docs/
├── docs.json                        # Mintlify config & navigation
├── index.mdx                        # Home page
├── quickstart.mdx                   # Getting-started guide
├── authentication.mdx               # Session + API key auth
├── api-reference/
│   ├── v2.mdx                       # Recommended API v2 overview
│   ├── openapi-v2.json              # API v2 endpoint reference
│   ├── introduction.mdx             # Legacy API v1 overview
│   └── openapi*.json                # Legacy API v1 endpoint specs
├── developers/
│   └── api-keys.mdx                 # API key management, plans, code examples
├── features/
│   ├── research-agent.mdx
│   └── alerts.mdx
└── mcp/                             # MCP Server documentation

​
Navigation

Navigation is configured in docs.json. The V2 API Reference and V1 API Reference tabs use Mintlify’s OpenAPI source feature to auto-generate one page per endpoint. 
{
  "tab": "V2 API Reference",
  "groups": [
    {
      "group": "Overview",
      "pages": ["api-reference/v2"]
    },
    {
      "group": "V2 Endpoints",
      "openapi": {
        "source": "api-reference/openapi-v2.json",
        "directory": "api-reference/v2-endpoints"
      }
    }
  ]
}
The v2 overview (api-reference/v2.mdx) and v1 overview (api-reference/introduction.mdx) are manually maintained. Endpoint pages are generated from their OpenAPI specs.

​
Authentication

All /api/v1/* endpoints require: 
Authorization: Bearer gdelt_sk_<64-hex-chars>
API keys are managed in the GDELT Cloud dashboard under Settings → API Keys.

​
Error Codes

HTTPerror fieldMeaning
401MISSING_API_KEYNo Authorization header
401INVALID_API_KEYKey not found / malformed
403API_ACCESS_DENIEDPlan does not include API access
429RATE_LIMITEDRPM limit exceeded
429QUOTA_EXCEEDEDMonthly QU limit reached
500INTERNAL_ERRORServer error